OLD | NEW |
| (Empty) |
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 | |
3 // found in the LICENSE file. | |
4 | |
5 // This file contains types/constants and functions specific to message pipes. | |
6 // | |
7 // Note: This header should be compilable as C. | |
8 | |
9 #ifndef MOJO_PUBLIC_C_INCLUDE_MOJO_SYSTEM_MESSAGE_PIPE_H_ | |
10 #define MOJO_PUBLIC_C_INCLUDE_MOJO_SYSTEM_MESSAGE_PIPE_H_ | |
11 | |
12 #include <mojo/macros.h> | |
13 #include <mojo/result.h> | |
14 #include <mojo/system/handle.h> | |
15 | |
16 // |MojoCreateMessagePipeOptions|: Used to specify creation parameters for a | |
17 // message pipe to |MojoCreateMessagePipe()|. | |
18 // |uint32_t struct_size|: Set to the size of the | |
19 // |MojoCreateMessagePipeOptions| struct. (Used to allow for future | |
20 // extensions.) | |
21 // |MojoCreateMessagePipeOptionsFlags flags|: Reserved for future use. | |
22 // |MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. | |
23 | |
24 typedef uint32_t MojoCreateMessagePipeOptionsFlags; | |
25 | |
26 #define MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE \ | |
27 ((MojoCreateMessagePipeOptionsFlags)0) | |
28 | |
29 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int64_t) == 8, "int64_t has weird alignment"); | |
30 struct MOJO_ALIGNAS(8) MojoCreateMessagePipeOptions { | |
31 uint32_t struct_size; | |
32 MojoCreateMessagePipeOptionsFlags flags; | |
33 }; | |
34 MOJO_STATIC_ASSERT(sizeof(struct MojoCreateMessagePipeOptions) == 8, | |
35 "MojoCreateMessagePipeOptions has wrong size"); | |
36 | |
37 // |MojoWriteMessageFlags|: Used to specify different modes to | |
38 // |MojoWriteMessage()|. | |
39 // |MOJO_WRITE_MESSAGE_FLAG_NONE| - No flags; default mode. | |
40 | |
41 typedef uint32_t MojoWriteMessageFlags; | |
42 | |
43 #define MOJO_WRITE_MESSAGE_FLAG_NONE ((MojoWriteMessageFlags)0) | |
44 | |
45 // |MojoReadMessageFlags|: Used to specify different modes to | |
46 // |MojoReadMessage()|. | |
47 // |MOJO_READ_MESSAGE_FLAG_NONE| - No flags; default mode. | |
48 // |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| - If the message is unable to be read | |
49 // for whatever reason (e.g., the caller-supplied buffer is too small), | |
50 // discard the message (i.e., simply dequeue it). | |
51 | |
52 typedef uint32_t MojoReadMessageFlags; | |
53 | |
54 #define MOJO_READ_MESSAGE_FLAG_NONE ((MojoReadMessageFlags)0) | |
55 #define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags)1 << 0) | |
56 | |
57 MOJO_BEGIN_EXTERN_C | |
58 | |
59 // |MojoCreateMessagePipe()|: Creates a message pipe, which is a bidirectional | |
60 // communication channel for framed data (i.e., messages). Messages can contain | |
61 // plain data and/or Mojo handles. | |
62 // | |
63 // |options| may be set to null for a message pipe with the default options. | |
64 // | |
65 // On success, |*message_pipe_handle0| and |*message_pipe_handle1| are set to | |
66 // handles for the two endpoints (ports) for the message pipe. Both handles have | |
67 // (at least) the following rights: |MOJO_HANDLE_RIGHT_TRANSFER|, | |
68 // |MOJO_HANDLE_RIGHT_READ|, |MOJO_HANDLE_RIGHT_WRITE|, | |
69 // |MOJO_HANDLE_RIGHT_GET_OPTIONS|, and |MOJO_HANDLE_RIGHT_SET_OPTIONS|. | |
70 // | |
71 // Returns: | |
72 // |MOJO_RESULT_OK| on success. | |
73 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | |
74 // |*options| is invalid). | |
75 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has | |
76 // been reached. | |
77 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. | |
78 MojoResult MojoCreateMessagePipe( | |
79 const struct MojoCreateMessagePipeOptions* MOJO_RESTRICT | |
80 options, // Optional in. | |
81 MojoHandle* MOJO_RESTRICT message_pipe_handle0, // Out. | |
82 MojoHandle* MOJO_RESTRICT message_pipe_handle1); // Out. | |
83 | |
84 // |MojoWriteMessage()|: Writes a message to the message pipe endpoint given by | |
85 // |message_pipe_handle| (which must have the |MOJO_HANDLE_RIGHT_WRITE| right), | |
86 // with message data specified by |bytes| of size |num_bytes| and attached | |
87 // handles specified by |handles| of count |num_handles|, and options specified | |
88 // by |flags|. If there is no message data, |bytes| may be null, in which case | |
89 // |num_bytes| must be zero. If there are no attached handles, |handles| may be | |
90 // null, in which case |num_handles| must be zero. | |
91 // | |
92 // If handles are attached, on success the handles will no longer be valid (the | |
93 // receiver will receive equivalent, but logically different, handles) and any | |
94 // ongoing two-phase operations (e.g., for data pipes) on them will be aborted. | |
95 // Handles to be sent should not be in simultaneous use (e.g., on another | |
96 // thread). On failure, any handles to be attached will remain valid (and | |
97 // two-phase operations will not be aborted). | |
98 // | |
99 // Returns: | |
100 // |MOJO_RESULT_OK| on success (i.e., the message was enqueued). | |
101 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if | |
102 // |message_pipe_handle| is not a valid handle, or some of the | |
103 // requirements above are not satisfied). | |
104 // |MOJO_RESULT_PERMISSION_DENIED| if |message_pipe_handle| does not have the | |
105 // |MOJO_HANDLE_RIGHT_WRITE| right or if one of the handles to be sent | |
106 // does not have the |MOJO_HANDLE_RIGHT_TRANSFER| right. | |
107 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if some system limit has been reached, or | |
108 // the number of handles to send is too large (TODO(vtl): reconsider the | |
109 // latter case). | |
110 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. | |
111 // Note that closing an endpoint is not necessarily synchronous (e.g., | |
112 // across processes), so this function may succeed even if the other | |
113 // endpoint has been closed (in which case the message would be dropped). | |
114 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. | |
115 // |MOJO_RESULT_BUSY| if |message_pipe_handle| is currently in use in some | |
116 // transaction (that, e.g., may result in it being invalidated, such as | |
117 // being sent in a message), or if some handle to be sent is currently in | |
118 // use. | |
119 // | |
120 // Note: |MOJO_RESULT_BUSY| is generally "preferred" over | |
121 // |MOJO_RESULT_PERMISSION_DENIED|. E.g., if a handle to be sent both is busy | |
122 // and does not have the transfer right, then the result will be "busy". | |
123 // | |
124 // TODO(vtl): We'll also report |MOJO_RESULT_BUSY| if a (data pipe | |
125 // producer/consumer) handle to be sent is in a two-phase write/read). But | |
126 // should we? (For comparison, there's no such provision in |MojoClose()|.) | |
127 // https://github.com/domokit/mojo/issues/782 | |
128 // | |
129 // TODO(vtl): Add a notion of capacity for message pipes, and return | |
130 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full. | |
131 MojoResult MojoWriteMessage(MojoHandle message_pipe_handle, // In. | |
132 const void* bytes, // Optional in. | |
133 uint32_t num_bytes, // In. | |
134 const MojoHandle* handles, // Optional in. | |
135 uint32_t num_handles, // In. | |
136 MojoWriteMessageFlags flags); // In. | |
137 | |
138 // |MojoReadMessage()|: Reads the next message from the message pipe endpoint | |
139 // given by |message_pipe_handle| (which must have the |MOJO_HANDLE_RIGHT_READ| | |
140 // right) or indicates the size of the message if it cannot fit in the provided | |
141 // buffers. The message will be read in its entirety or not at all; if it is | |
142 // not, it will remain enqueued unless the |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| | |
143 // flag was passed. At most one message will be consumed from the queue, and the | |
144 // return value will indicate whether a message was successfully read. | |
145 // | |
146 // |num_bytes| and |num_handles| are optional in/out parameters that on input | |
147 // must be set to the sizes of the |bytes| and |handles| arrays, and on output | |
148 // will be set to the actual number of bytes or handles contained in the | |
149 // message (even if the message was not retrieved due to being too large). | |
150 // Either |num_bytes| or |num_handles| may be null if the message is not | |
151 // expected to contain the corresponding type of data, but such a call would | |
152 // fail with |MOJO_RESULT_RESOURCE_EXHAUSTED| if the message in fact did | |
153 // contain that type of data. | |
154 // | |
155 // |bytes| and |handles| will receive the contents of the message, if it is | |
156 // retrieved. Either or both may be null, in which case the corresponding size | |
157 // parameter(s) must also be set to zero or passed as null. | |
158 // | |
159 // Returns: | |
160 // |MOJO_RESULT_OK| on success (i.e., a message was actually read). | |
161 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid. | |
162 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. | |
163 // |MOJO_RESULT_PERMISSION_DENIED| if |message_pipe_handle| does not have the | |
164 // |MOJO_HANDLE_RIGHT_READ| right. | |
165 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the message was too large to fit in the | |
166 // provided buffer(s). The message will have been left in the queue or | |
167 // discarded, depending on flags. | |
168 // |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read. | |
169 // |MOJO_RESULT_BUSY| if |message_pipe_handle| is currently in use in some | |
170 // transaction (that, e.g., may result in it being invalidated, such as | |
171 // being sent in a message). | |
172 // | |
173 // TODO(vtl): Reconsider the |MOJO_RESULT_RESOURCE_EXHAUSTED| error code; should | |
174 // distinguish this from the hitting-system-limits case. | |
175 MojoResult MojoReadMessage( | |
176 MojoHandle message_pipe_handle, // In. | |
177 void* MOJO_RESTRICT bytes, // Optional out. | |
178 uint32_t* MOJO_RESTRICT num_bytes, // Optional in/out. | |
179 MojoHandle* MOJO_RESTRICT handles, // Optional out. | |
180 uint32_t* MOJO_RESTRICT num_handles, // Optional in/out. | |
181 MojoReadMessageFlags flags); // In. | |
182 | |
183 MOJO_END_EXTERN_C | |
184 | |
185 #endif // MOJO_PUBLIC_C_INCLUDE_MOJO_SYSTEM_MESSAGE_PIPE_H_ | |
OLD | NEW |