Debian Codegraph @

build-aux/qmi-codegen/Client.py

raw
1 # -*- Mode: python; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
2 #
3 # This program is free software; you can redistribute it and/or modify it under
4 # the terms of the GNU Lesser General Public License as published by the Free
5 # Software Foundation; either version 2 of the License, or (at your option) any
6 # later version.
7 #
8 # This program is distributed in the hope that it will be useful, but WITHOUT
9 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
10 # FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
11 # details.
12 #
13 # You should have received a copy of the GNU Lesser General Public License along
14 # with this program; if not, write to the Free Software Foundation, Inc., 51
15 # Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
16 #
17 # Copyright (C) 2012 Lanedo GmbH
18 # Copyright (C) 2012-2022 Aleksander Morgado <[email protected]>
19 #
20
21 import string
22
23 from MessageList import MessageList
24 import utils
25
26 """
27 The Client class is responsible for providing the QmiClient-based service
28 specific client GObject.
29 """
30 class Client:
31
32 """
33 Constructor
34 """
35 def __init__(self, objects_dictionary):
36 self.name = None
37 self.service = None
38 self.description = ''
39
40 # Loop items in the list, looking for the special 'Client' type
41 for object_dictionary in objects_dictionary:
42 if object_dictionary['type'] == 'Client':
43 self.name = object_dictionary['name']
44 self.since = object_dictionary['since'] if 'since' in object_dictionary else ''
45 elif object_dictionary['type'] == 'Service':
46 self.service = object_dictionary['name']
47
48 if not self.description:
49 self.description = object_dictionary.get('description', '')
50
51 # We NEED the Client field and the Service field
52 if self.name is None:
53 raise ValueError('Missing Client field')
54 if self.service is None:
55 raise ValueError('Missing Service field')
56
57 """
58 Emits the symbol specifying if the service is supported
59 """
60 def __emit_supported(self, f, supported):
61 translations = { 'service' : self.service.upper() }
62 template = '\n'
63 if supported:
64 template += '#define HAVE_QMI_SERVICE_${service}\n'
65 else:
66 template += '/* HAVE_QMI_SERVICE_${service} */\n'
67 f.write(string.Template(template).substitute(translations))
68
69 """
70 Emits the generic GObject class implementation
71 """
72 def __emit_class(self, hfile, cfile, message_list):
73 translations = { 'underscore' : utils.build_underscore_name(self.name),
74 'no_prefix_underscore_upper' : utils.build_underscore_name(self.name[4:]).upper(),
75 'camelcase' : utils.build_camelcase_name(self.name),
76 'hyphened' : utils.build_dashed_name(self.name),
77 'since' : self.since,
78 'service' : self.service.upper() }
79
80 # Emit class header
81 template = (
82 '#define QMI_TYPE_${no_prefix_underscore_upper} (${underscore}_get_type ())\n'
83 '#define QMI_${no_prefix_underscore_upper}(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), QMI_TYPE_${no_prefix_underscore_upper}, ${camelcase}))\n'
84 '#define QMI_${no_prefix_underscore_upper}_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), QMI_TYPE_${no_prefix_underscore_upper}, ${camelcase}Class))\n'
85 '#define QMI_IS_${no_prefix_underscore_upper}(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), QMI_TYPE_${no_prefix_underscore_upper}))\n'
86 '#define QMI_IS_${no_prefix_underscore_upper}_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), QMI_TYPE_${no_prefix_underscore_upper}))\n'
87 '#define QMI_${no_prefix_underscore_upper}_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), QMI_TYPE_${no_prefix_underscore_upper}, ${camelcase}Class))\n'
88 '\n'
89 'typedef struct _${camelcase} ${camelcase};\n'
90 'typedef struct _${camelcase}Class ${camelcase}Class;\n'
91 '\n')
92 if self.service != 'CTL':
93 template += (
94 '/**\n'
95 ' * ${camelcase}:\n'
96 ' *\n'
97 ' * #QmiClient which handles operations in the ${service} service.\n'
98 ' *\n'
99 ' * The #${camelcase} structure contains private data and should only be accessed\n'
100 ' * using the provided API.\n'
101 ' *\n'
102 ' * Since: ${since}\n'
103 ' */\n')
104 template += (
105 'struct _${camelcase} {\n'
106 ' /*< private >*/\n'
107 ' QmiClient parent;\n'
108 ' gpointer priv_unused;\n'
109 '};\n'
110 '\n'
111 'struct _${camelcase}Class {\n'
112 ' /*< private >*/\n'
113 ' QmiClientClass parent;\n'
114 '};\n'
115 '\n'
116 'GType ${underscore}_get_type (void);\n'
117 'G_DEFINE_AUTOPTR_CLEANUP_FUNC (${camelcase}, g_object_unref)\n')
118 hfile.write(string.Template(template).substitute(translations))
119
120 template = ''
121 template += (
122 'G_DEFINE_TYPE (${camelcase}, ${underscore}, QMI_TYPE_CLIENT)\n')
123
124 if len(message_list.indication_list) > 0:
125 template += (
126 '\n'
127 'enum {\n')
128 for message in message_list.indication_list:
129 translations['signal_id'] = utils.build_underscore_uppercase_name(message.name)
130 inner_template = (
131 ' SIGNAL_${signal_id},\n')
132 template += string.Template(inner_template).substitute(translations)
133 template += (
134 ' SIGNAL_LAST\n'
135 '};\n'
136 '\n'
137 'static guint signals[SIGNAL_LAST] = { 0 };\n')
138
139 template += (
140 '\n'
141 'static void\n'
142 'process_indication (QmiClient *self,\n'
143 ' QmiMessage *message)\n'
144 '{\n'
145 ' switch (qmi_message_get_message_id (message)) {\n')
146
147 for message in message_list.indication_list:
148 translations['enum_name'] = message.id_enum_name
149 translations['message_fullname_underscore'] = utils.build_underscore_name(message.fullname)
150 translations['message_name'] = message.name
151 translations['signal_id'] = utils.build_underscore_uppercase_name(message.name)
152 inner_template = ''
153 if message.output is not None and message.output.fields is not None:
154 # At least one field in the indication
155 translations['output_camelcase'] = utils.build_camelcase_name(message.output.fullname)
156 translations['output_underscore'] = utils.build_underscore_name(message.output.fullname)
157 translations['output_underscore'] = utils.build_underscore_name(message.output.fullname)
158 inner_template += (
159 ' case ${enum_name}: {\n'
160 ' ${output_camelcase} *output;\n'
161 ' GError *error = NULL;\n'
162 '\n'
163 ' /* Parse indication */\n'
164 ' output = ${message_fullname_underscore}_indication_parse (message, &error);\n'
165 ' if (!output) {\n'
166 ' g_warning ("Couldn\'t parse \'${message_name}\' indication: %s",\n'
167 ' error ? error->message : "Unknown error");\n'
168 ' if (error)\n'
169 ' g_error_free (error);\n'
170 ' } else {\n'
171 ' g_signal_emit (self, signals[SIGNAL_${signal_id}], 0, output);\n'
172 ' ${output_underscore}_unref (output);\n'
173 ' }\n'
174 ' break;\n'
175 ' }\n')
176 else:
177 # No output field in the indication
178 inner_template += (
179 ' case ${enum_name}: {\n'
180 ' g_signal_emit (self, signals[SIGNAL_${signal_id}], 0, NULL);\n'
181 ' break;\n'
182 ' }\n')
183
184 template += string.Template(inner_template).substitute(translations)
185
186 template += (
187 ' default:\n'
188 ' break;\n'
189 ' }\n'
190 '}\n'
191 '\n'
192 'static void\n'
193 '${underscore}_init (${camelcase} *self)\n'
194 '{\n'
195 '}\n'
196 '\n'
197 'static void\n'
198 '${underscore}_class_init (${camelcase}Class *klass)\n'
199 '{\n'
200 ' QmiClientClass *client_class = QMI_CLIENT_CLASS (klass);\n'
201 '\n'
202 ' client_class->process_indication = process_indication;\n')
203
204 for message in message_list.indication_list:
205 translations['signal_name'] = utils.build_dashed_name(message.name)
206 translations['signal_id'] = utils.build_underscore_uppercase_name(message.name)
207 translations['message_name'] = message.name
208 translations['since'] = message.since
209 inner_template = ''
210 if message.output is not None and message.output.fields is not None:
211 # At least one field in the indication
212 translations['output_camelcase'] = utils.build_camelcase_name(message.output.fullname)
213 translations['bundle_type'] = 'QMI_TYPE_' + utils.remove_prefix(utils.build_underscore_uppercase_name(message.output.fullname), 'QMI_')
214 translations['service'] = self.service.upper()
215 translations['message_name_dashed'] = message.name.replace(' ', '-')
216 inner_template += (
217 '\n')
218 if self.service != 'CTL':
219 inner_template += (
220 ' /**\n'
221 ' * ${camelcase}::${signal_name}:\n'
222 ' * @object: A #${camelcase}.\n'
223 ' * @output: A #${output_camelcase}.\n'
224 ' *\n'
225 ' * The ::${signal_name} signal gets emitted when a \'<link linkend=\"libqmi-glib-${service}-${message_name_dashed}-indication.top_of_page\">${message_name}</link>\' indication is received.\n'
226 ' *\n'
227 ' * Since: ${since}\n'
228 ' */\n')
229 inner_template += (
230 ' signals[SIGNAL_${signal_id}] =\n'
231 ' g_signal_new ("${signal_name}",\n'
232 ' G_OBJECT_CLASS_TYPE (G_OBJECT_CLASS (klass)),\n'
233 ' G_SIGNAL_RUN_LAST,\n'
234 ' 0,\n'
235 ' NULL,\n'
236 ' NULL,\n'
237 ' NULL,\n'
238 ' G_TYPE_NONE,\n'
239 ' 1,\n'
240 ' ${bundle_type});\n')
241 else:
242 # No output field in the indication
243 inner_template += (
244 '\n')
245 if self.service != 'CTL':
246 inner_template += (
247 ' /**\n'
248 ' * ${camelcase}::${signal_name}:\n'
249 ' * @object: A #${camelcase}.\n'
250 ' *\n'
251 ' * The ::${signal_name} signal gets emitted when a \'${message_name}\' indication is received.\n'
252 ' *\n'
253 ' * Since: ${since}\n'
254 ' */\n')
255 inner_template += (
256 ' signals[SIGNAL_${signal_id}] =\n'
257 ' g_signal_new ("${signal_name}",\n'
258 ' G_OBJECT_CLASS_TYPE (G_OBJECT_CLASS (klass)),\n'
259 ' G_SIGNAL_RUN_LAST,\n'
260 ' 0,\n'
261 ' NULL,\n'
262 ' NULL,\n'
263 ' NULL,\n'
264 ' G_TYPE_NONE,\n'
265 ' 0);\n')
266 template += string.Template(inner_template).substitute(translations)
267
268 template += (
269 '}\n'
270 '\n')
271 cfile.write(string.Template(template).substitute(translations))
272
273
274 """
275 Emits the async methods for each known request/response
276 """
277 def __emit_methods(self, hfile, cfile, message_list):
278 translations = { 'underscore' : utils.build_underscore_name(self.name),
279 'camelcase' : utils.build_camelcase_name (self.name),
280 'service_lowercase' : self.service.lower(),
281 'service_uppercase' : self.service.upper(),
282 'service_camelcase' : string.capwords(self.service) }
283
284 for message in message_list.request_list:
285 if message.static:
286 continue
287
288 translations['message_name'] = message.name
289 translations['message_vendor_id'] = message.vendor
290 translations['message_underscore'] = utils.build_underscore_name(message.name)
291 translations['message_fullname_underscore'] = utils.build_underscore_name(message.fullname)
292 translations['input_camelcase'] = utils.build_camelcase_name(message.input.fullname)
293 translations['output_camelcase'] = utils.build_camelcase_name(message.output.fullname)
294 translations['input_underscore'] = utils.build_underscore_name(message.input.fullname)
295 translations['output_underscore'] = utils.build_underscore_name(message.output.fullname)
296 translations['message_since'] = message.since
297
298 if message.input.fields is None:
299 translations['input_arg'] = 'gpointer unused'
300 translations['input_var'] = 'NULL'
301 translations['input_doc'] = 'unused: %NULL. This message doesn\'t have any input bundle.'
302 else:
303 translations['input_arg'] = translations['input_camelcase'] + ' *input'
304 translations['input_var'] = 'input'
305 translations['input_doc'] = 'input: a #' + translations['input_camelcase'] + '.'
306 template = (
307 '\n')
308 if self.service != 'CTL':
309 template += (
310 '/**\n'
311 ' * ${underscore}_${message_underscore}:\n'
312 ' * @self: a #${camelcase}.\n'
313 ' * @${input_doc}\n'
314 ' * @timeout: maximum time to wait for the method to complete, in seconds.\n'
315 ' * @cancellable: a #GCancellable or %NULL.\n'
316 ' * @callback: a #GAsyncReadyCallback to call when the request is satisfied.\n'
317 ' * @user_data: user data to pass to @callback.\n'
318 ' *\n'
319 ' * Asynchronously sends a ${message_name} request to the device.\n')
320
321 if message.abort:
322 template += (
323 ' *\n'
324 ' * This message is abortable. If @cancellable is cancelled or if @timeout expires,\n'
325 ' * an abort request will be sent to the device, and the asynchronous operation will\n'
326 ' * not return until the abort response is received. It is not an error if a successful\n'
327 ' * response is returned for the asynchronous operation even after the user has cancelled\n'
328 ' * the cancellable, because it may happen that the response is received before the\n'
329 ' * modem had a chance to run the abort.\n')
330
331 template += (
332 ' *\n'
333 ' * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from.\n'
334 ' *\n'
335 ' * You can then call ${underscore}_${message_underscore}_finish() to get the result of the operation.\n'
336 ' *\n'
337 ' * Since: ${message_since}\n'
338 ' */\n')
339 template += (
340 'void ${underscore}_${message_underscore} (\n'
341 ' ${camelcase} *self,\n'
342 ' ${input_arg},\n'
343 ' guint timeout,\n'
344 ' GCancellable *cancellable,\n'
345 ' GAsyncReadyCallback callback,\n'
346 ' gpointer user_data);\n'
347 '\n')
348 if self.service != 'CTL':
349 template += (
350 '/**\n'
351 ' * ${underscore}_${message_underscore}_finish:\n'
352 ' * @self: a #${camelcase}.\n'
353 ' * @res: the #GAsyncResult obtained from the #GAsyncReadyCallback passed to ${underscore}_${message_underscore}().\n'
354 ' * @error: Return location for error or %NULL.\n'
355 ' *\n'
356 ' * Finishes an async operation started with ${underscore}_${message_underscore}().\n'
357 ' *\n'
358 ' * Returns: a #${output_camelcase}, or %NULL if @error is set. The returned value should be freed with ${output_underscore}_unref().\n'
359 ' *\n'
360 ' * Since: ${message_since}\n'
361 ' */\n')
362 template += (
363 '${output_camelcase} *${underscore}_${message_underscore}_finish (\n'
364 ' ${camelcase} *self,\n'
365 ' GAsyncResult *res,\n'
366 ' GError **error);\n')
367 hfile.write(string.Template(template).substitute(translations))
368
369 template = (
370 '\n'
371 '${output_camelcase} *\n'
372 '${underscore}_${message_underscore}_finish (\n'
373 ' ${camelcase} *self,\n'
374 ' GAsyncResult *res,\n'
375 ' GError **error)\n'
376 '{\n'
377 ' return g_task_propagate_pointer (G_TASK (res), error);\n'
378 '}\n')
379
380 if message.abort:
381 template += (
382 '\n'
383 '#if defined HAVE_QMI_MESSAGE_${service_uppercase}_ABORT\n'
384 '\n'
385 'static QmiMessage *\n'
386 '__${message_fullname_underscore}_abortable_build_request (\n'
387 ' QmiDevice *self,\n'
388 ' QmiMessage *message,\n'
389 ' QmiClient *client,\n'
390 ' GError **error)\n'
391 '{\n'
392 ' QmiMessage *abort_request;\n'
393 ' guint16 transaction_id;\n'
394 ' g_autoptr(QmiMessage${service_camelcase}AbortInput) input = NULL;\n'
395 '\n'
396 ' transaction_id = qmi_message_get_transaction_id (message);\n'
397 ' g_assert (transaction_id != 0);\n'
398 '\n'
399 ' input = qmi_message_${service_lowercase}_abort_input_new ();\n'
400 ' qmi_message_${service_lowercase}_abort_input_set_transaction_id (\n'
401 ' input,\n'
402 ' transaction_id,\n'
403 ' NULL);\n'
404 ' abort_request = __qmi_message_${service_lowercase}_abort_request_create (\n'
405 ' qmi_client_get_next_transaction_id (client),\n'
406 ' qmi_client_get_cid (client),\n'
407 ' input,\n'
408 ' NULL);\n'
409 ' return abort_request;\n'
410 '}\n'
411 '\n'
412 'static gboolean\n'
413 '__${message_fullname_underscore}_abortable_parse_response (\n'
414 ' QmiDevice *self,\n'
415 ' QmiMessage *abort_response,\n'
416 ' QmiClient *client,\n'
417 ' GError **error)\n'
418 '{\n'
419 ' g_autoptr(QmiMessage${service_camelcase}AbortOutput) output = NULL;\n'
420 '\n'
421 ' output = __qmi_message_${service_lowercase}_abort_response_parse (\n'
422 ' abort_response,\n'
423 ' error);\n'
424 ' return !!output;\n'
425 '}\n'
426 '\n'
427 '#endif /* HAVE_QMI_MESSAGE_${service_uppercase}_ABORT */\n'
428 '\n')
429
430 template += (
431 '\n'
432 'static void\n'
433 '${message_underscore}_ready (\n'
434 ' QmiDevice *device,\n'
435 ' GAsyncResult *res,\n'
436 ' GTask *task)\n'
437 '{\n'
438 ' GError *error = NULL;\n'
439 ' QmiMessage *reply;\n'
440 ' ${output_camelcase} *output;\n'
441 '\n')
442
443 if message.abort:
444 template += (
445 ' reply = qmi_device_command_abortable_finish (device, res, &error);\n')
446 else:
447 template += (
448 ' reply = qmi_device_command_full_finish (device, res, &error);\n')
449
450 template += (
451 ' if (!reply) {\n')
452
453 template += (
454 ' g_task_return_error (task, error);\n'
455 ' g_object_unref (task);\n'
456 ' return;\n'
457 ' }\n'
458 '\n'
459 ' /* Parse reply */\n'
460 ' output = ${message_fullname_underscore}_response_parse (reply, &error);\n'
461 ' if (!output)\n'
462 ' g_task_return_error (task, error);\n'
463 ' else\n'
464 ' g_task_return_pointer (task,\n'
465 ' output,\n'
466 ' (GDestroyNotify)${output_underscore}_unref);\n'
467 ' g_object_unref (task);\n'
468 ' qmi_message_unref (reply);\n'
469 '}\n'
470 '\n'
471 'void\n'
472 '${underscore}_${message_underscore} (\n'
473 ' ${camelcase} *self,\n'
474 ' ${input_arg},\n'
475 ' guint timeout,\n'
476 ' GCancellable *cancellable,\n'
477 ' GAsyncReadyCallback callback,\n'
478 ' gpointer user_data)\n'
479 '{\n'
480 ' GTask *task;\n'
481 ' GError *error = NULL;\n'
482 ' guint16 transaction_id;\n'
483 ' g_autoptr(QmiMessage) request = NULL;\n')
484
485 if message.vendor is not None:
486 template += (
487 ' g_autoptr(QmiMessageContext) context = NULL;\n')
488
489 template += (
490 '\n'
491 ' task = g_task_new (self, cancellable, callback, user_data);\n'
492 ' if (!qmi_client_is_valid (QMI_CLIENT (self))) {\n'
493 ' g_task_return_new_error (task, QMI_CORE_ERROR, QMI_CORE_ERROR_WRONG_STATE, "client invalid");\n'
494 ' g_object_unref (task);\n'
495 ' return;\n'
496 ' }\n'
497 '\n'
498 ' transaction_id = qmi_client_get_next_transaction_id (QMI_CLIENT (self));\n'
499 '\n'
500 ' request = __${message_fullname_underscore}_request_create (\n'
501 ' transaction_id,\n'
502 ' qmi_client_get_cid (QMI_CLIENT (self)),\n'
503 ' ${input_var},\n'
504 ' &error);\n'
505 ' if (!request) {\n'
506 ' g_prefix_error (&error, "Couldn\'t create request message: ");\n'
507 ' g_task_return_error (task, error);\n'
508 ' g_object_unref (task);\n'
509 ' return;\n'
510 ' }\n')
511
512 if message.vendor is not None:
513 template += (
514 '\n'
515 ' context = qmi_message_context_new ();\n'
516
517 ' qmi_message_context_set_vendor_id (context, ${message_vendor_id});\n')
518
519 if message.abort:
520 template += (
521 '\n'
522 ' qmi_device_command_abortable (QMI_DEVICE (qmi_client_peek_device (QMI_CLIENT (self))),\n')
523 else:
524 template += (
525 '\n'
526 ' qmi_device_command_full (QMI_DEVICE (qmi_client_peek_device (QMI_CLIENT (self))),\n')
527
528 template += (
529 ' request,\n')
530
531 if message.vendor is not None:
532 template += (
533 ' context,\n')
534 else:
535 template += (
536 ' NULL,\n')
537
538 template += (
539 ' timeout,\n')
540
541 if message.abort:
542 template += (
543 '#if defined HAVE_QMI_MESSAGE_${service_uppercase}_ABORT\n'
544 ' (QmiDeviceCommandAbortableBuildRequestFn) __${message_fullname_underscore}_abortable_build_request,\n'
545 ' (QmiDeviceCommandAbortableParseResponseFn) __${message_fullname_underscore}_abortable_parse_response,\n'
546 ' g_object_ref (self),\n'
547 ' g_object_unref,\n'
548 '#else\n'
549 ' NULL,\n'
550 ' NULL,\n'
551 ' NULL,\n'
552 ' NULL,\n'
553 '#endif\n')
554
555 template += (
556 ' cancellable,\n'
557 ' (GAsyncReadyCallback)${message_underscore}_ready,\n'
558 ' task);\n')
559
560 template += (
561 '}\n'
562 '\n')
563 cfile.write(string.Template(template).substitute(translations))
564
565
566 """
567 Emit the service-specific client implementation
568 """
569 def emit(self, hfile, cfile, message_list):
570 # Do nothing if no supported messages
571 if len(message_list.indication_list) == 0 and len(message_list.request_list) == 0:
572 self.__emit_supported(hfile, False)
573 return
574
575 self.__emit_supported(hfile, True)
576
577 # First, emit common class code
578 utils.add_separator(hfile, 'CLIENT', self.name);
579 utils.add_separator(cfile, 'CLIENT', self.name);
580 self.__emit_class(hfile, cfile, message_list)
581 self.__emit_methods(hfile, cfile, message_list)
582
583
584 """
585 Emit the sections
586 """
587 def emit_sections(self, sfile, message_list):
588 # Do nothing if no supported messages
589 if len(message_list.indication_list) == 0 and len(message_list.request_list) == 0:
590 return
591
592 translations = { 'underscore' : utils.build_underscore_name(self.name),
593 'description' : self.description,
594 'no_prefix_underscore_upper' : utils.build_underscore_name(self.name[4:]).upper(),
595 'camelcase' : utils.build_camelcase_name (self.name),
596 'hyphened' : utils.build_dashed_name (self.name),
597 'service_uppercase' : self.service.upper() }
598
599 template = (
600 'title: ${service_uppercase} - ${description}\n'
601 'slug: ${hyphened}\n'
602 '\n'
603 '# Client\n'
604 '[class@${camelcase}] - QmiClient for the ${service_uppercase} service\n'
605 '\n'
606 '# Messages\n'
607 '\n'
608 'Messages of the ${service_uppercase} service\n'
609 '\n')
610 sfile.write(string.Template(template).substitute(translations))