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 #ifndef MOJO_PUBLIC_C_BINDINGS_ARRAY_H_ | |
6 #define MOJO_PUBLIC_C_BINDINGS_ARRAY_H_ | |
7 | |
8 #include <mojo/macros.h> | |
9 #include <stdint.h> | |
10 | |
11 #include "mojo/public/c/bindings/buffer.h" | |
12 #include "mojo/public/c/bindings/lib/type_descriptor.h" | |
13 | |
14 MOJO_BEGIN_EXTERN_C | |
15 | |
16 // The fields below are just the header of a mojom array. The bytes that | |
17 // immediately follow this struct consist of |num_bytes - | |
18 // sizeof(MojomArrayHeader)| bytes describing |num_elements| elements of the | |
19 // array. | |
20 struct MojomArrayHeader { | |
21 // num_bytes includes the size of this struct along with the accompanying | |
22 // array bytes that follow these fields. | |
23 uint32_t num_bytes; | |
24 uint32_t num_elements; | |
25 }; | |
26 MOJO_STATIC_ASSERT(sizeof(struct MojomArrayHeader) == 8, | |
27 "struct MojomArrayHeader must be 8 bytes."); | |
28 | |
29 // This union is used to represent references to a mojom array. | |
30 union MojomArrayHeaderPtr { | |
31 // |ptr| is used to access the array when it hasn't been encoded yet. | |
32 struct MojomArrayHeader* ptr; | |
33 // |offset| is used to access the array after it has been encoded. | |
34 uint64_t offset; | |
35 }; | |
36 MOJO_STATIC_ASSERT(sizeof(union MojomArrayHeaderPtr) == 8, | |
37 "union MojomArrayHeaderPtr must be 8 bytes."); | |
38 | |
39 // Allocates enough space using the given |buffer| for |num_elements|, each of | |
40 // which is |element_byte_size| bytes in size. Returns NULL on failure. | |
41 struct MojomArrayHeader* MojomArray_New(struct MojomBuffer* buffer, | |
42 uint32_t num_elements, | |
43 uint32_t element_byte_size); | |
44 | |
45 // This is a macro for accessing a particular element in a mojom array. Given | |
46 // |base|, which pointers to a |struct MojomArrayHeader|, extracts the |index|th | |
47 // element, where each element is |sizeof(type)| bytes. | |
48 #define MOJOM_ARRAY_INDEX(base, type, index) \ | |
49 ((type*)((char*)(base) + sizeof(struct MojomArrayHeader) + \ | |
50 sizeof(type) * (index))) | |
51 | |
52 // Returns the number of bytes required to serialize this mojom array. | |
53 // |in_type_desc| is the generated descriptor entry that describes |in_array|. | |
54 // The user isn't expected to call this function directly, but this will | |
55 // probably be called when |ComputeSerializedSize()|ing a user-defined mojom | |
56 // struct. | |
57 size_t MojomArray_ComputeSerializedSize( | |
58 const struct MojomTypeDescriptorArray* in_type_desc, | |
59 const struct MojomArrayHeader* in_array_data); | |
60 | |
61 // Encodes the mojom array described by the |inout_array| buffer; note that any | |
62 // references from the array are also in the buffer backed by |inout_array|, and | |
63 // they are recursively encoded. Encodes all pointers to relative offsets, and | |
64 // encodes all handles by moving them into |inout_handles_buffer| and encoding | |
65 // the index into the handle. | |
66 // |in_type_desc|: Describes the pointer and handle fields of the mojom array. | |
67 // |inout_array|: Contains the array, and any other references outside the | |
68 // array. | |
69 // |in_array_size|: Size of the buffer backed by |inout_array| in bytes. | |
70 // |inout_handles_buffer|: | |
71 // A buffer used to record handles during encoding. The |num_handles_used| | |
72 // field can be used to determine how many handles were moved into this | |
73 // buffer after this function returns. | |
74 void MojomArray_EncodePointersAndHandles( | |
75 const struct MojomTypeDescriptorArray* in_type_desc, | |
76 struct MojomArrayHeader* inout_array, | |
77 uint32_t in_array_size, | |
78 struct MojomHandleBuffer* inout_handles_buffer); | |
79 | |
80 // Decodes the mojom array described by the |inout_array| buffer; note that any | |
81 // references from the array are also in the buffer backed by |inout_array|, and | |
82 // they are recursively decoded. Decodes all offset to pointers, and decodes all | |
83 // handles by moving them out of |inout_handles| array using the encoded index. | |
84 // |in_type_desc|: Describes the pointer and handle fields of the mojom array. | |
85 // |inout_array|: Contains the array, and any other references outside the | |
86 // array. | |
87 // |in_array_size|: Size of the buffer backed by |inout_array|. | |
88 // |inout_handles|: Mojo handles are moved out of this array, and are references | |
89 // by index in |inout_buf|. | |
90 // |in_num_handles|: Size in # of number elements available in |inout_handles|. | |
91 void MojomArray_DecodePointersAndHandles( | |
92 const struct MojomTypeDescriptorArray* in_type_desc, | |
93 struct MojomArrayHeader* inout_array, | |
94 uint32_t in_array_size, | |
95 MojoHandle* inout_handles, | |
96 uint32_t in_num_handles); | |
97 | |
98 // Validates the mojom array described by the |in_struct| buffer. Any | |
99 // references from the array are also recursively validated, and are expected | |
100 // to be in the same buffer backing |in_array|. | |
101 // |in_type_desc|: Describes the pointer and handle fields of the mojom array. | |
102 // |in_array|: Buffer containing the array, and any other references outside of | |
103 // the array | |
104 // |in_array_size|: Size of the buffer backed by |in_array| in bytes. | |
105 // |in_num_handles|: Number of valid handles expected to be referenced from | |
106 // |in_array|. | |
107 // |inout_context|: An initialized context that contains the expected location | |
108 // of the next pointer and next offset. This is used to | |
109 // validate that no two pointers or handles are shared. | |
110 MojomValidationResult MojomArray_Validate( | |
111 const struct MojomTypeDescriptorArray* in_type_desc, | |
112 const struct MojomArrayHeader* in_array, | |
113 uint32_t in_array_size, | |
114 uint32_t in_num_handles, | |
115 struct MojomValidationContext* inout_context); | |
116 | |
117 // Creates a new copy of |in_array| using |buffer| to allocate space. | |
118 // Recursively creates new copies of any references from |in_array|, and updates | |
119 // the references to point to the new copies. This operation is useful if you | |
120 // want to linearize |in_array| using the buffer backed by |buffer|. If there is | |
121 // insufficient space in the buffer or has unknown-typed data, this function | |
122 // returns false and the supplied buffer may be partially used. Otherwise, | |
123 // |out_array| is set to the new copy of the struct. | |
124 // |buffer|: A mojom buffer used to allocate space for the new array. | |
125 // |in_type_desc|: Describes the pointer and handle fields of the mojom array. | |
126 // |in_array|: The unencoded mojom array to be copied. | |
127 // |out_array|: Will be set to the new unencoded mojom array. | |
128 bool MojomArray_DeepCopy(struct MojomBuffer* buffer, | |
129 const struct MojomTypeDescriptorArray* in_type_desc, | |
130 const struct MojomArrayHeader* in_array, | |
131 struct MojomArrayHeader** out_array); | |
132 | |
133 MOJO_END_EXTERN_C | |
134 | |
135 #endif // MOJO_PUBLIC_C_BINDINGS_ARRAY_H_ | |
OLD | NEW |