| OLD | NEW |
| 1 // Copyright 2014 The Chromium Authors. All rights reserved. | 1 // Copyright 2014 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/constants and functions specific to buffers (and in | 5 // This file contains types/constants and functions specific to buffers (and in |
| 6 // particular shared buffers). | 6 // particular shared buffers). |
| 7 // TODO(vtl): Reorganize this file (etc.) to separate general buffer functions | 7 // TODO(vtl): Reorganize this file (etc.) to separate general buffer functions |
| 8 // from (shared) buffer creation. | 8 // from (shared) buffer creation. |
| 9 // | 9 // |
| 10 // Note: This header should be compilable as C. | 10 // Note: This header should be compilable as C. |
| 11 | 11 |
| 12 #ifndef MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ | 12 #ifndef MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ |
| 13 #define MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ | 13 #define MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ |
| 14 | 14 |
| 15 #include "mojo/public/c/system/macros.h" | 15 #include "mojo/public/c/system/macros.h" |
| 16 #include "mojo/public/c/system/system_export.h" | |
| 17 #include "mojo/public/c/system/types.h" | 16 #include "mojo/public/c/system/types.h" |
| 18 | 17 |
| 19 // |MojoCreateSharedBufferOptions|: Used to specify creation parameters for a | 18 // |MojoCreateSharedBufferOptions|: Used to specify creation parameters for a |
| 20 // shared buffer to |MojoCreateSharedBuffer()|. | 19 // shared buffer to |MojoCreateSharedBuffer()|. |
| 21 // |uint32_t struct_size|: Set to the size of the | 20 // |uint32_t struct_size|: Set to the size of the |
| 22 // |MojoCreateSharedBufferOptions| struct. (Used to allow for future | 21 // |MojoCreateSharedBufferOptions| struct. (Used to allow for future |
| 23 // extensions.) | 22 // extensions.) |
| 24 // |MojoCreateSharedBufferOptionsFlags flags|: Reserved for future use. | 23 // |MojoCreateSharedBufferOptionsFlags flags|: Reserved for future use. |
| 25 // |MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE|: No flags; default mode. | 24 // |MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE|: No flags; default mode. |
| 26 // | 25 // |
| (...skipping 80 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 107 // undefined behavior. | 106 // undefined behavior. |
| 108 // | 107 // |
| 109 // Returns: | 108 // Returns: |
| 110 // |MOJO_RESULT_OK| on success. | 109 // |MOJO_RESULT_OK| on success. |
| 111 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 110 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
| 112 // |*options| is invalid). | 111 // |*options| is invalid). |
| 113 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has | 112 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has |
| 114 // been reached (e.g., if the requested size was too large, or if the | 113 // been reached (e.g., if the requested size was too large, or if the |
| 115 // maximum number of handles was exceeded). | 114 // maximum number of handles was exceeded). |
| 116 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. | 115 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. |
| 117 MOJO_SYSTEM_EXPORT MojoResult MojoCreateSharedBuffer( | 116 MojoResult MojoCreateSharedBuffer( |
| 118 const struct MojoCreateSharedBufferOptions* options, // Optional. | 117 const struct MojoCreateSharedBufferOptions* options, // Optional. |
| 119 uint64_t num_bytes, // In. | 118 uint64_t num_bytes, // In. |
| 120 MojoHandle* shared_buffer_handle); // Out. | 119 MojoHandle* shared_buffer_handle); // Out. |
| 121 | 120 |
| 122 // Duplicates the handle |buffer_handle| to a buffer. This creates another | 121 // Duplicates the handle |buffer_handle| to a buffer. This creates another |
| 123 // handle (returned in |*new_buffer_handle| on success), which can then be sent | 122 // handle (returned in |*new_buffer_handle| on success), which can then be sent |
| 124 // to another application over a message pipe, while retaining access to the | 123 // to another application over a message pipe, while retaining access to the |
| 125 // |buffer_handle| (and any mappings that it may have). | 124 // |buffer_handle| (and any mappings that it may have). |
| 126 // | 125 // |
| 127 // |options| may be set to null to duplicate the buffer handle with the default | 126 // |options| may be set to null to duplicate the buffer handle with the default |
| 128 // options. | 127 // options. |
| 129 // | 128 // |
| 130 // On success, |*shared_buffer_handle| will be set to the handle for the new | 129 // On success, |*shared_buffer_handle| will be set to the handle for the new |
| 131 // buffer handle. (On failure, it is not modified.) | 130 // buffer handle. (On failure, it is not modified.) |
| 132 // | 131 // |
| 133 // Returns: | 132 // Returns: |
| 134 // |MOJO_RESULT_OK| on success. | 133 // |MOJO_RESULT_OK| on success. |
| 135 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 134 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
| 136 // |buffer_handle| is not a valid buffer handle or |*options| is invalid). | 135 // |buffer_handle| is not a valid buffer handle or |*options| is invalid). |
| 137 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. | 136 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. |
| 138 MOJO_SYSTEM_EXPORT MojoResult MojoDuplicateBufferHandle( | 137 MojoResult MojoDuplicateBufferHandle( |
| 139 MojoHandle buffer_handle, | 138 MojoHandle buffer_handle, |
| 140 const struct MojoDuplicateBufferHandleOptions* options, // Optional. | 139 const struct MojoDuplicateBufferHandleOptions* options, // Optional. |
| 141 MojoHandle* new_buffer_handle); // Out. | 140 MojoHandle* new_buffer_handle); // Out. |
| 142 | 141 |
| 143 // Maps the part (at offset |offset| of length |num_bytes|) of the buffer given | 142 // Maps the part (at offset |offset| of length |num_bytes|) of the buffer given |
| 144 // by |buffer_handle| into memory, with options specified by |flags|. |offset + | 143 // by |buffer_handle| into memory, with options specified by |flags|. |offset + |
| 145 // num_bytes| must be less than or equal to the size of the buffer. On success, | 144 // num_bytes| must be less than or equal to the size of the buffer. On success, |
| 146 // |*buffer| points to memory with the requested part of the buffer. (On | 145 // |*buffer| points to memory with the requested part of the buffer. (On |
| 147 // failure, it is not modified.) | 146 // failure, it is not modified.) |
| 148 // | 147 // |
| 149 // A single buffer handle may have multiple active mappings (possibly depending | 148 // A single buffer handle may have multiple active mappings (possibly depending |
| 150 // on the buffer type). The permissions (e.g., writable or executable) of the | 149 // on the buffer type). The permissions (e.g., writable or executable) of the |
| 151 // returned memory may depend on the properties of the buffer and properties | 150 // returned memory may depend on the properties of the buffer and properties |
| 152 // attached to the buffer handle as well as |flags|. | 151 // attached to the buffer handle as well as |flags|. |
| 153 // | 152 // |
| 154 // Note: Though data outside the specified range may apparently be | 153 // Note: Though data outside the specified range may apparently be |
| 155 // available/visible/readable/writable, trying to use those extra bytes is | 154 // available/visible/readable/writable, trying to use those extra bytes is |
| 156 // undefined behavior. | 155 // undefined behavior. |
| 157 // | 156 // |
| 158 // Returns: | 157 // Returns: |
| 159 // |MOJO_RESULT_OK| on success. | 158 // |MOJO_RESULT_OK| on success. |
| 160 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 159 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
| 161 // |buffer_handle| is not a valid buffer handle or the range specified by | 160 // |buffer_handle| is not a valid buffer handle or the range specified by |
| 162 // |offset| and |num_bytes| is not valid). | 161 // |offset| and |num_bytes| is not valid). |
| 163 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the mapping operation itself failed | 162 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the mapping operation itself failed |
| 164 // (e.g., due to not having appropriate address space available). | 163 // (e.g., due to not having appropriate address space available). |
| 165 MOJO_SYSTEM_EXPORT MojoResult MojoMapBuffer(MojoHandle buffer_handle, | 164 MojoResult MojoMapBuffer(MojoHandle buffer_handle, |
| 166 uint64_t offset, | 165 uint64_t offset, |
| 167 uint64_t num_bytes, | 166 uint64_t num_bytes, |
| 168 void** buffer, // Out. | 167 void** buffer, // Out. |
| 169 MojoMapBufferFlags flags); | 168 MojoMapBufferFlags flags); |
| 170 | 169 |
| 171 // Unmaps a buffer pointer that was mapped by |MojoMapBuffer()|. |buffer| must | 170 // Unmaps a buffer pointer that was mapped by |MojoMapBuffer()|. |buffer| must |
| 172 // have been the result of |MojoMapBuffer()| (not some other pointer inside | 171 // have been the result of |MojoMapBuffer()| (not some other pointer inside |
| 173 // the mapped memory), and the entire mapping will be removed (partial unmapping | 172 // the mapped memory), and the entire mapping will be removed (partial unmapping |
| 174 // is not supported). A mapping may only be unmapped once. | 173 // is not supported). A mapping may only be unmapped once. |
| 175 // | 174 // |
| 176 // Returns: | 175 // Returns: |
| 177 // |MOJO_RESULT_OK| on success. | 176 // |MOJO_RESULT_OK| on success. |
| 178 // |MOJO_RESULT_INVALID_ARGUMENT| if |buffer| is invalid (e.g., is not the | 177 // |MOJO_RESULT_INVALID_ARGUMENT| if |buffer| is invalid (e.g., is not the |
| 179 // result of |MojoMapBuffer()| or has already been unmapped). | 178 // result of |MojoMapBuffer()| or has already been unmapped). |
| 180 MOJO_SYSTEM_EXPORT MojoResult MojoUnmapBuffer(void* buffer); // In. | 179 MojoResult MojoUnmapBuffer(void* buffer); // In. |
| 181 | 180 |
| 182 #ifdef __cplusplus | 181 #ifdef __cplusplus |
| 183 } // extern "C" | 182 } // extern "C" |
| 184 #endif | 183 #endif |
| 185 | 184 |
| 186 #endif // MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ | 185 #endif // MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ |
| OLD | NEW |