OLD | NEW |
1 // Copyright 2016 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 // This file contains types/functions and constants for platform handle wrapping | 5 // This file contains types/functions and constants for platform handle wrapping |
6 // and unwrapping APIs. | 6 // and unwrapping APIs. |
7 // | 7 // |
8 // Note: This header should be compilable as C. | 8 // Note: This header should be compilable as C. |
9 | 9 |
10 #ifndef MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ | 10 #ifndef MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ |
(...skipping 27 matching lines...) Expand all Loading... |
38 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR = 1; | 38 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR = 1; |
39 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT = 2; | 39 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT = 2; |
40 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE = 3; | 40 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE = 3; |
41 #else | 41 #else |
42 #define MOJO_PLATFORM_HANDLE_TYPE_INVALID ((MojoPlatformHandleType)0) | 42 #define MOJO_PLATFORM_HANDLE_TYPE_INVALID ((MojoPlatformHandleType)0) |
43 #define MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR ((MojoPlatformHandleType)1) | 43 #define MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR ((MojoPlatformHandleType)1) |
44 #define MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT ((MojoPlatformHandleType)2) | 44 #define MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT ((MojoPlatformHandleType)2) |
45 #define MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE ((MojoPlatformHandleType)3) | 45 #define MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE ((MojoPlatformHandleType)3) |
46 #endif | 46 #endif |
47 | 47 |
48 // |MojoPlatformHandle|: A handle to an OS object. | 48 // |MojoPlatformHandle|: A handle to a native platform object. |
| 49 // |
49 // |uint32_t struct_size|: The size of this structure. Used for versioning | 50 // |uint32_t struct_size|: The size of this structure. Used for versioning |
50 // to allow for future extensions. | 51 // to allow for future extensions. |
| 52 // |
51 // |MojoPlatformHandleType type|: The type of handle stored in |value|. | 53 // |MojoPlatformHandleType type|: The type of handle stored in |value|. |
| 54 // |
52 // |uint64_t value|: The value of this handle. Ignored if |type| is | 55 // |uint64_t value|: The value of this handle. Ignored if |type| is |
53 // MOJO_PLATFORM_HANDLE_TYPE_INVALID. | 56 // MOJO_PLATFORM_HANDLE_TYPE_INVALID. Otherwise the meaning of this |
| 57 // value depends on the value of |type|. |
54 // | 58 // |
55 | 59 |
56 struct MOJO_ALIGNAS(8) MojoPlatformHandle { | 60 struct MOJO_ALIGNAS(8) MojoPlatformHandle { |
57 uint32_t struct_size; | 61 uint32_t struct_size; |
58 MojoPlatformHandleType type; | 62 MojoPlatformHandleType type; |
59 uint64_t value; | 63 uint64_t value; |
60 }; | 64 }; |
61 MOJO_STATIC_ASSERT(sizeof(MojoPlatformHandle) == 16, | 65 MOJO_STATIC_ASSERT(sizeof(MojoPlatformHandle) == 16, |
62 "MojoPlatformHandle has wrong size"); | 66 "MojoPlatformHandle has wrong size"); |
63 | 67 |
(...skipping 13 matching lines...) Expand all Loading... |
77 const MojoPlatformSharedBufferHandleFlags | 81 const MojoPlatformSharedBufferHandleFlags |
78 MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY = 1 << 0; | 82 MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY = 1 << 0; |
79 #else | 83 #else |
80 #define MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE \ | 84 #define MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE \ |
81 ((MojoPlatformSharedBufferHandleFlags)0) | 85 ((MojoPlatformSharedBufferHandleFlags)0) |
82 | 86 |
83 #define MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY \ | 87 #define MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY \ |
84 ((MojoPlatformSharedBufferHandleFlags)1 << 0) | 88 ((MojoPlatformSharedBufferHandleFlags)1 << 0) |
85 #endif | 89 #endif |
86 | 90 |
87 // Wraps a generic platform handle as a Mojo handle which can be transferred | 91 // Wraps a native platform handle as a Mojo handle which can be transferred |
88 // over a message pipe. Takes ownership of the underlying platform object. | 92 // over a message pipe. Takes ownership of the underlying native platform |
| 93 // object. |
89 // | 94 // |
90 // |platform_handle|: The platform handle to wrap. | 95 // |platform_handle|: The platform handle to wrap. |
91 // | 96 // |
92 // Returns: | 97 // Returns: |
93 // |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case | 98 // |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case |
94 // |*mojo_handle| contains the Mojo handle of the wrapped object. | 99 // |*mojo_handle| contains the Mojo handle of the wrapped object. |
95 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the system is out of handles. | 100 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the system is out of handles. |
96 // |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid | 101 // |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid |
97 // platform handle. | 102 // platform handle. |
98 // | 103 // |
99 // NOTE: It is not always possible to detect if |platform_handle| is valid, | 104 // NOTE: It is not always possible to detect if |platform_handle| is valid, |
100 // particularly when |platform_handle->type| is valid but | 105 // particularly when |platform_handle->type| is valid but |
101 // |platform_handle->value| does not represent a valid platform object. | 106 // |platform_handle->value| does not represent a valid platform object. |
102 MOJO_SYSTEM_EXPORT MojoResult | 107 MOJO_SYSTEM_EXPORT MojoResult |
103 MojoWrapPlatformHandle(const struct MojoPlatformHandle* platform_handle, | 108 MojoWrapPlatformHandle(const struct MojoPlatformHandle* platform_handle, |
104 MojoHandle* mojo_handle); // Out | 109 MojoHandle* mojo_handle); // Out |
105 | 110 |
106 // Unwraps a generic platform handle from a Mojo handle. If this call succeeds, | 111 // Unwraps a native platform handle from a Mojo handle. If this call succeeds, |
107 // ownership of the underlying platform object is bound to the returned platform | 112 // ownership of the underlying platform object is assumed by the caller. The |
108 // handle and becomes the caller's responsibility. The Mojo handle is always | 113 // The Mojo handle is always closed regardless of success or failure. |
109 // closed regardless of success or failure. | |
110 // | 114 // |
111 // |mojo_handle|: The Mojo handle from which to unwrap the platform handle. | 115 // |mojo_handle|: The Mojo handle from which to unwrap the native platform |
| 116 // handle. |
112 // | 117 // |
113 // Returns: | 118 // Returns: |
114 // |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case | 119 // |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case |
115 // |*platform_handle| contains the unwrapped platform handle. | 120 // |*platform_handle| contains the unwrapped platform handle. |
116 // |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| was not a valid Mojo | 121 // |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| was not a valid Mojo |
117 // handle wrapping a platform handle. | 122 // handle wrapping a platform handle. |
118 MOJO_SYSTEM_EXPORT MojoResult | 123 MOJO_SYSTEM_EXPORT MojoResult |
119 MojoUnwrapPlatformHandle(MojoHandle mojo_handle, | 124 MojoUnwrapPlatformHandle(MojoHandle mojo_handle, |
120 struct MojoPlatformHandle* platform_handle); // Out | 125 struct MojoPlatformHandle* platform_handle); // Out |
121 | 126 |
122 // Wraps a platform shared buffer handle as a Mojo shared buffer handle which | 127 // Wraps a native platform shared buffer handle as a Mojo shared buffer handle |
123 // can be transferred over a message pipe. Takes ownership of the platform | 128 // which can be used exactly like a shared buffer handle created by |
124 // shared buffer handle. | 129 // |MojoCreateSharedBuffer()| or |MojoDuplicateBufferHandle()|. |
125 // | 130 // |
126 // |platform_handle|: The platform handle to wrap. Must be a handle to a | 131 // Takes ownership of the native platform shared buffer handle. |
| 132 // |
| 133 // |platform_handle|: The platform handle to wrap. Must be a native handle to a |
127 // shared buffer object. | 134 // shared buffer object. |
128 // |num_bytes|: The size of the shared buffer in bytes. | 135 // |num_bytes|: The size of the shared buffer in bytes. |
129 // |flags|: Flags which influence the treatment of the shared buffer object. See | 136 // |flags|: Flags which influence the treatment of the shared buffer object. See |
130 // below. | 137 // below. |
131 // | 138 // |
132 // Flags: | 139 // Flags: |
133 // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE| indicates default behavior. | 140 // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE| indicates default behavior. |
134 // No flags set. | 141 // No flags set. |
135 // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY| indicates that the | 142 // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY| indicates that the |
136 // buffer handled to be wrapped may only be mapped as read-only. This | 143 // buffer handled to be wrapped may only be mapped as read-only. This |
137 // flag does NOT change the access control of the buffer in any way. | 144 // flag does NOT change the access control of the buffer in any way. |
138 // | 145 // |
139 // Returns: | 146 // Returns: |
140 // |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case | 147 // |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case |
141 // |*mojo_handle| contains a Mojo shared buffer handle. | 148 // |*mojo_handle| contains a Mojo shared buffer handle. |
142 // |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid | 149 // |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid |
143 // platform shared buffer handle. | 150 // platform shared buffer handle. |
144 MOJO_SYSTEM_EXPORT MojoResult | 151 MOJO_SYSTEM_EXPORT MojoResult |
145 MojoWrapPlatformSharedBufferHandle( | 152 MojoWrapPlatformSharedBufferHandle( |
146 const struct MojoPlatformHandle* platform_handle, | 153 const struct MojoPlatformHandle* platform_handle, |
147 size_t num_bytes, | 154 size_t num_bytes, |
148 MojoPlatformSharedBufferHandleFlags flags, | 155 MojoPlatformSharedBufferHandleFlags flags, |
149 MojoHandle* mojo_handle); // Out | 156 MojoHandle* mojo_handle); // Out |
150 | 157 |
151 // Unwraps a platform shared buffer handle from a Mojo shared buffer handle. | 158 // Unwraps a native platform shared buffer handle from a Mojo shared buffer |
152 // If this call succeeds, ownership of the underlying shared buffer object is | 159 // handle. If this call succeeds, ownership of the underlying shared buffer |
153 // bound to the returned platform handle and becomes the caller's | 160 // object is assumed by the caller. |
154 // responsibility. The Mojo handle is always closed regardless of success or | 161 // |
155 // failure. | 162 // The Mojo handle is always closed regardless of success or failure. |
156 // | 163 // |
157 // |mojo_handle|: The Mojo shared buffer handle to unwrap. | 164 // |mojo_handle|: The Mojo shared buffer handle to unwrap. |
158 // | 165 // |
159 // |platform_handle|, |num_bytes| and |flags| are used to receive output values | 166 // |platform_handle|, |num_bytes| and |flags| are used to receive output values |
160 // and MUST always be non-null. | 167 // and MUST always be non-null. |
161 // | 168 // |
162 // Returns: | 169 // Returns: |
163 // |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case | 170 // |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case |
164 // |*platform_handle| contains a platform shared buffer handle, | 171 // |*platform_handle| contains a platform shared buffer handle, |
165 // |*num_bytes| contains the size of the shared buffer object, and | 172 // |*num_bytes| contains the size of the shared buffer object, and |
166 // |*flags| indicates flags relevant to the wrapped buffer (see below). | 173 // |*flags| indicates flags relevant to the wrapped buffer (see below). |
167 // |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| is not a valid Mojo | 174 // |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| is not a valid Mojo |
168 // shared buffer handle. | 175 // shared buffer handle. |
169 // | 176 // |
170 // Flags which may be set in |*flags| upon success: | 177 // Flags which may be set in |*flags| upon success: |
171 // |MOJO_PLATFORM_SHARED_BUFFER_FLAG_READ_ONLY| is set iff the unwrapped | 178 // |MOJO_PLATFORM_SHARED_BUFFER_FLAG_READ_ONLY| is set iff the unwrapped |
172 // shared buffer handle may only be mapped as read-only. | 179 // shared buffer handle may only be mapped as read-only. |
173 MOJO_SYSTEM_EXPORT MojoResult | 180 MOJO_SYSTEM_EXPORT MojoResult |
174 MojoUnwrapPlatformSharedBufferHandle( | 181 MojoUnwrapPlatformSharedBufferHandle( |
175 MojoHandle mojo_handle, | 182 MojoHandle mojo_handle, |
176 struct MojoPlatformHandle* platform_handle, | 183 struct MojoPlatformHandle* platform_handle, |
177 size_t* num_bytes, | 184 size_t* num_bytes, |
178 MojoPlatformSharedBufferHandleFlags* flags); | 185 MojoPlatformSharedBufferHandleFlags* flags); |
179 | 186 |
180 #ifdef __cplusplus | 187 #ifdef __cplusplus |
181 } // extern "C" | 188 } // extern "C" |
182 #endif | 189 #endif |
183 | 190 |
184 #endif // MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ | 191 #endif // MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ |
OLD | NEW |