Debian Codegraph @

src/libqmi-glib/qmi-message-context.h

raw
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
3 /*
4 * libqmi-glib -- GLib/GIO based library to control QMI devices
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301 USA.
20 *
21 * Copyright (C) 2017 Aleksander Morgado <[email protected]>
22 */
23
24 #ifndef _LIBQMI_GLIB_QMI_MESSAGE_CONTEXT_H_
25 #define _LIBQMI_GLIB_QMI_MESSAGE_CONTEXT_H_
26
27 #if !defined (__LIBQMI_GLIB_H_INSIDE__) && !defined (LIBQMI_GLIB_COMPILATION)
28 #error "Only <libqmi-glib.h> can be included directly."
29 #endif
30
31 #include <glib.h>
32 #include <glib-object.h>
33
34 G_BEGIN_DECLS
35
36 /**
37 * SECTION:qmi-message-context
38 * @short_description: the QMI message context
39 *
40 * The #QmiMessageContext defines non-standard features of the QMI message
41 * associated with it, which may be required for a correct processing.
42 *
43 * The main purpose of this type is to provide a common context when processing
44 * the request sent and the response received, so that the reception logic
45 * can know in advance the type of response expected. Therefore, when a context
46 * is given when sending a request with qmi_device_command_full(), the same
47 * context will then be applied for the associated response.
48 *
49 * If there are multiple types of messages using the same service and command
50 * id, the context is flagged as vendor-specific automatically, by assigning
51 * a specific vendor id in the #QmiMessageContext. This does not mean that the
52 * command will only be available for that specific vendor id, it is just a way
53 * to make a difference among commands that have the same command id and a
54 * totally different meaning. The actual vendor id value given in the context is
55 * therefore really irrelevant, as long as the vendor id is different to the
56 * other vendor ids specified for other commands reusing the same command id. In
57 * order to simplify the selection of the vendor id, the library will use the
58 * standard vendor-specific USB vendor id.
59 */
60
61 /**
62 * QmiMessageContext:
63 *
64 * An opaque type representing a QMI message context.
65 *
66 * Since: 1.18
67 */
68 typedef struct _QmiMessageContext QmiMessageContext;
69
70 GType qmi_message_context_get_type (void);
71
72 /*****************************************************************************/
73 /* Basic context */
74
75 /**
76 * qmi_message_context_new:
77 *
78 * Create a new empty #QmiMessageContext.
79 *
80 * Returns: (transfer full): a newly created #QmiMessageContext. The returned value should be freed with qmi_message_context_unref().
81 *
82 * Since: 1.18
83 */
84 QmiMessageContext *qmi_message_context_new (void);
85
86 /**
87 * qmi_message_context_ref:
88 * @self: a #QmiMessageContext.
89 *
90 * Atomically increments the reference count of @self by one.
91 *
92 * Returns: (transfer full): the new reference to @self.
93 *
94 * Since: 1.18
95 */
96 QmiMessageContext *qmi_message_context_ref (QmiMessageContext *self);
97
98 /**
99 * qmi_message_context_unref:
100 * @self: a #QmiMessageContext.
101 *
102 * Atomically decrements the reference count of @self by one.
103 * If the reference count drops to 0, @self is completely disposed.
104 *
105 * Since: 1.18
106 */
107 void qmi_message_context_unref (QmiMessageContext *self);
108 G_DEFINE_AUTOPTR_CLEANUP_FUNC (QmiMessageContext, qmi_message_context_unref)
109
110 /*****************************************************************************/
111 /* Vendor ID */
112
113 /**
114 * QMI_MESSAGE_VENDOR_GENERIC:
115 *
116 * Generic vendor id (0x0000).
117 *
118 * Since: 1.18
119 */
120 #define QMI_MESSAGE_VENDOR_GENERIC 0x0000
121
122 /**
123 * qmi_message_context_set_vendor_id:
124 * @self: a #QmiMessageContext.
125 * @vendor_id: the vendor ID.
126 *
127 * Sets the vendor ID associated to the message.
128 *
129 * Since: 1.18
130 */
131 void qmi_message_context_set_vendor_id (QmiMessageContext *self,
132 guint16 vendor_id);
133
134 /**
135 * qmi_message_context_get_vendor_id:
136 * @self: a #QmiMessageContext.
137 *
138 * Gets the vendor ID associated to the message.
139 *
140 * Returns: the vendor ID.
141 *
142 * Since: 1.18
143 */
144 guint16 qmi_message_context_get_vendor_id (QmiMessageContext *self);
145
146 G_END_DECLS
147
148 #endif /* _LIBQMI_GLIB_QMI_MESSAGE_CONTEXT_H_ */