OLD | NEW |
| (Empty) |
1 // Copyright 2016 The Chromium Authors. All rights reserved. | |
2 // Use of this source code is governed by a BSD-style license that can be | |
3 // found in the LICENSE file. | |
4 | |
5 // This file contains structs used for constructing type descriptors for | |
6 // generated mojom types. A type descriptor for a mojom struct is a table | |
7 // describing the byte-offsets of all the pointers and handles in the struct, | |
8 // and has references to the type descriptorss that further describe the | |
9 // pointers. The table is used for doing all computations for the struct -- | |
10 // determining serialized size, encoding and decoding recursively, etc. A type | |
11 // descriptor is generated for each struct, union, array and map. Mojom maps are | |
12 // just mojom structs with two mojom arrays. We denote it as a separate type, | |
13 // but it is described the same way as a mojom struct. | |
14 // | |
15 // The user is not expected to construct type descriptors -- a bindings | |
16 // generator will do this when it generates bindings for a mojom file. | |
17 // | |
18 // A type descriptor for a mojom struct is a |MojomTypeDescriptorStruct| | |
19 // containing an array of entries of types of |MojomTypeDescriptorStructEntry|. | |
20 // Similarly, unions are described with |MojomTypeDescriptorUnion| with entries | |
21 // of |MojomTypeDescriptorUnionEntry|. Arrays are described with | |
22 // |MojomTypeDescriptorArray|. | |
23 | |
24 #ifndef MOJO_PUBLIC_C_BINDINGS_LIB_TYPE_DESCRIPTOR_H_ | |
25 #define MOJO_PUBLIC_C_BINDINGS_LIB_TYPE_DESCRIPTOR_H_ | |
26 | |
27 #include <mojo/macros.h> | |
28 #include <mojo/system/handle.h> | |
29 #include <stdbool.h> | |
30 #include <stddef.h> | |
31 #include <stdint.h> | |
32 | |
33 #include "mojo/public/c/bindings/buffer.h" | |
34 #include "mojo/public/c/bindings/lib/util.h" | |
35 #include "mojo/public/c/bindings/validation.h" | |
36 | |
37 MOJO_BEGIN_EXTERN_C | |
38 | |
39 // This enum is used in a type descriptor entry for the |elem_type| field, and | |
40 // indicates which type the accompanying |elem_descriptor| is describing (if it | |
41 // is describing a reference type), or to indicate that it's a handle type. | |
42 // Values that correspond to an |elem_descriptor|'s pointer type: | |
43 // - If MOJOM_TYPE_DESCRIPTOR_TYPE_STRUCT_PTR, then |elem_descriptor| points to | |
44 // a |MojomTypeDescriptorStruct|. | |
45 // - If MOJOM_TYPE_DESCRIPTOR_TYPE_MAP_PTR, then |elem_descriptor| points to | |
46 // a |MojomTypeDescriptorStruct|. | |
47 // - If MOJOM_TYPE_DESCRIPTOR_TYPE_UNION or | |
48 // MOJOM_TYPE_DESCRIPTOR_TYPE_UNION_PTR, then |elem_descriptor| points to a | |
49 // |MojomTypeDescriptorUnion|. | |
50 // - If MOJOM_TYPE_DESCRIPTOR_TYPE_ARRAY_PTR, then |elem_descriptor| points to a | |
51 // |MojomTypeDescriptorArray|. | |
52 // - For any other value, |elem_descriptor| is NULL. | |
53 enum MojomTypeDescriptorType { | |
54 // Note: A map is a mojom struct with 2 mojom arrays, so we don't have a | |
55 // separate descriptor type for it. | |
56 MOJOM_TYPE_DESCRIPTOR_TYPE_STRUCT_PTR = 0, | |
57 MOJOM_TYPE_DESCRIPTOR_TYPE_MAP_PTR = 1, | |
58 MOJOM_TYPE_DESCRIPTOR_TYPE_ARRAY_PTR = 2, | |
59 // A MOJOM_TYPE_DESCRIPTOR_TYPE_UNION_PTR only occurs inside a | |
60 // |MojomTypeDescriptorUnion|, since union fields inside unions are encoded as | |
61 // pointers to an out-of-line union. | |
62 MOJOM_TYPE_DESCRIPTOR_TYPE_UNION_PTR = 3, | |
63 // A union that is not inside a union is inlined, and described by | |
64 // MOJOM_TYPE_DESCRIPTOR_TYPE_UNION. | |
65 MOJOM_TYPE_DESCRIPTOR_TYPE_UNION = 4, | |
66 MOJOM_TYPE_DESCRIPTOR_TYPE_HANDLE = 5, | |
67 MOJOM_TYPE_DESCRIPTOR_TYPE_INTERFACE = 6, | |
68 // This is only used in an array descriptor, and serves as a way to terminate | |
69 // a chain of array descriptors; the last entry in the chain always contains a | |
70 // plain-old-data type. | |
71 MOJOM_TYPE_DESCRIPTOR_TYPE_POD = 7, | |
72 }; | |
73 | |
74 struct MojomTypeDescriptorStructVersion { | |
75 uint32_t version; | |
76 uint32_t num_bytes; | |
77 }; | |
78 | |
79 // Mojom structs are described using this struct. | |
80 struct MojomTypeDescriptorStruct { | |
81 uint32_t num_versions; | |
82 // Increasing ordered by version. | |
83 struct MojomTypeDescriptorStructVersion* versions; | |
84 // |entries| is an array of |num_entries|, each describing a field of | |
85 // reference or handle type. | |
86 uint32_t num_entries; | |
87 const struct MojomTypeDescriptorStructEntry* entries; | |
88 }; | |
89 | |
90 // This struct is used to describe each entry in a mojom struct. Each entry | |
91 // indicates whether it is describing a reference type, or a handle type through | |
92 // the field |elem_type|. |elem_descriptor| points to the type descriptor | |
93 // describing the field, if the type has one (handles don't have type | |
94 // descriptors). |offset| indicates the starting byte offset of the element | |
95 // within the struct. | |
96 struct MojomTypeDescriptorStructEntry { | |
97 // See comments for |MojomTypeDescriptorType| on possible values and | |
98 // corresponding behaviour with |elem_descriptor|. | |
99 enum MojomTypeDescriptorType elem_type; | |
100 // Use |elem_type| to decide which type |elem_descriptor| should be casted to. | |
101 const void* elem_descriptor; | |
102 // |offset| does not account for the struct header. Offset 0 always refers to | |
103 // the first element. | |
104 uint32_t offset; | |
105 // Corresponds to the '[MinVersion]' attribute in mojom IDL. This determines | |
106 // if this field should be ignored if its min_version < version of the struct | |
107 // we are dealing with. | |
108 uint32_t min_version; | |
109 // Is this field nullable? | |
110 bool nullable; | |
111 }; | |
112 | |
113 // Mojom unions are described using this struct. | |
114 struct MojomTypeDescriptorUnion { | |
115 // Number of fields in the union. | |
116 uint32_t num_fields; | |
117 // Number of elements in the |entries| array below. | |
118 uint32_t num_entries; | |
119 // |entries| only includes entries for pointer and handle types. | |
120 const struct MojomTypeDescriptorUnionEntry* entries; | |
121 }; | |
122 | |
123 // Like |MojomTypeDescriptorStructEntry|, this variant is used to construct a | |
124 // type descriptor for a union. Instead of an offset, it describes a union field | |
125 // by its |tag|. | |
126 struct MojomTypeDescriptorUnionEntry { | |
127 // See comments for |MojomTypeDescriptorType| on possible values and | |
128 // corresponding behaviour with |elem_descriptor|. | |
129 enum MojomTypeDescriptorType elem_type; | |
130 const void* elem_descriptor; | |
131 // The tag of the union field. | |
132 uint32_t tag; | |
133 bool nullable; | |
134 }; | |
135 | |
136 // Describes a mojom array. To describe an array, we don't need a table of | |
137 // entries, since arrays can only describe 1 type. However, that one type can | |
138 // recursively be an array (e.g, array<array<int>>), in which case a chain of | |
139 // array entries are constructed. | |
140 struct MojomTypeDescriptorArray { | |
141 enum MojomTypeDescriptorType elem_type; | |
142 const void* elem_descriptor; | |
143 // How many elements is this array expected to hold? | |
144 // 0 means unspecified. | |
145 uint32_t num_elements; | |
146 // Size of each element, in bits (since bools are 1-bit in size). This is | |
147 // needed to validate the size of an array. | |
148 uint32_t elem_num_bits; | |
149 bool nullable; | |
150 }; | |
151 | |
152 // This describes a mojom string. | |
153 // A mojom string is a mojom array of chars without a fixed-sized. | |
154 extern const struct MojomTypeDescriptorArray g_mojom_string_type_description; | |
155 | |
156 // Returns true if |type| is a "pointer" type: an array or a struct, whose data | |
157 // is referenced by a pointer (or an offset, if serialized). | |
158 // Since unions being pointer types depends on their container, we don't include | |
159 // them here. | |
160 bool MojomType_IsPointer(enum MojomTypeDescriptorType type); | |
161 | |
162 // This helper function, depending on |type|, calls the appropriate | |
163 // *_ComputeSerializedSize(|type_desc|, |data|). | |
164 size_t MojomType_DispatchComputeSerializedSize( | |
165 enum MojomTypeDescriptorType type, | |
166 const void* type_desc, | |
167 bool nullable, | |
168 const void* data); | |
169 | |
170 // This helper function, depending on |in_elem_type|, calls the appropriate | |
171 // *_EncodePointersAndHandles(...). If |in_elem_type| describes a pointer, it | |
172 // first encodes the pointer before calling the associated | |
173 // *_EncodePointersAndHandles(...). If |in_elem_type| describes a handle, it | |
174 // encodes the handle into |inout_handles|. | |
175 void MojomType_DispatchEncodePointersAndHandles( | |
176 enum MojomTypeDescriptorType in_elem_type, | |
177 const void* in_type_desc, | |
178 bool in_nullable, | |
179 void* inout_buf, | |
180 uint32_t in_buf_size, | |
181 struct MojomHandleBuffer* inout_handles_buffer); | |
182 | |
183 // This helper function, depending on |in_elem_type|, calls the appropriate | |
184 // *_DecodePointersAndHandles(...). If |in_elem_type| describes a pointer, it | |
185 // first decodes the offset into a pointer before calling the associated | |
186 // *_DecodePointersAndHandles(...). If |in_elem_type| describes a handle, it | |
187 // decodes the handle by looking up it up in |inout_handles|. | |
188 void MojomType_DispatchDecodePointersAndHandles( | |
189 enum MojomTypeDescriptorType in_elem_type, | |
190 const void* in_type_desc, | |
191 bool in_nullable, | |
192 void* inout_buf, | |
193 uint32_t in_buf_size, | |
194 MojoHandle* inout_handles, | |
195 uint32_t in_num_handles); | |
196 | |
197 MojomValidationResult MojomType_DispatchValidate( | |
198 enum MojomTypeDescriptorType in_elem_type, | |
199 const void* in_type_desc, | |
200 bool in_nullable, | |
201 const void* in_buf, | |
202 uint32_t in_buf_size, | |
203 uint32_t in_num_handles, | |
204 struct MojomValidationContext* inout_context); | |
205 | |
206 // This helper function, depending on |in_elem_type|, calls the appropriate | |
207 // *_DeepCopy(...). The result of that call is then assigned to |out_data|. If | |
208 // |in_type_type| describes a pointer to a union, it allocates space for the | |
209 // new union before dispatching a call to MojomUnion_DeepCopy. Returns false if | |
210 // the copy failed due to insufficient space in the buffer. | |
211 bool MojomType_DispatchDeepCopy(struct MojomBuffer* buffer, | |
212 enum MojomTypeDescriptorType in_elem_type, | |
213 const void* in_type_desc, | |
214 const void* in_data, | |
215 void* out_data); | |
216 | |
217 MOJO_END_EXTERN_C | |
218 | |
219 #endif // MOJO_PUBLIC_C_BINDINGS_LIB_TYPE_DESCRIPTOR_H_ | |
OLD | NEW |