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 message pipes. | 5 // This file contains types/constants and functions specific to message pipes. |
6 // | 6 // |
7 // Note: This header should be compilable as C. | 7 // Note: This header should be compilable as C. |
8 | 8 |
9 #ifndef MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ | 9 #ifndef MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ |
10 #define MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ | 10 #define MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ |
(...skipping 10 matching lines...) Expand all Loading... |
21 // |MojoCreateMessagePipeOptionsFlags flags|: Reserved for future use. | 21 // |MojoCreateMessagePipeOptionsFlags flags|: Reserved for future use. |
22 // |MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. | 22 // |MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. |
23 | 23 |
24 typedef uint32_t MojoCreateMessagePipeOptionsFlags; | 24 typedef uint32_t MojoCreateMessagePipeOptionsFlags; |
25 | 25 |
26 #ifdef __cplusplus | 26 #ifdef __cplusplus |
27 const MojoCreateMessagePipeOptionsFlags | 27 const MojoCreateMessagePipeOptionsFlags |
28 MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE = 0; | 28 MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE = 0; |
29 #else | 29 #else |
30 #define MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE \ | 30 #define MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE \ |
31 ((MojoCreateMessagePipeOptionsFlags) 0) | 31 ((MojoCreateMessagePipeOptionsFlags)0) |
32 #endif | 32 #endif |
33 | 33 |
34 MOJO_COMPILE_ASSERT(MOJO_ALIGNOF(int64_t) == 8, int64_t_has_weird_alignment); | 34 MOJO_COMPILE_ASSERT(MOJO_ALIGNOF(int64_t) == 8, int64_t_has_weird_alignment); |
35 struct MOJO_ALIGNAS(8) MojoCreateMessagePipeOptions { | 35 struct MOJO_ALIGNAS(8) MojoCreateMessagePipeOptions { |
36 uint32_t struct_size; | 36 uint32_t struct_size; |
37 MojoCreateMessagePipeOptionsFlags flags; | 37 MojoCreateMessagePipeOptionsFlags flags; |
38 }; | 38 }; |
39 MOJO_COMPILE_ASSERT(sizeof(MojoCreateMessagePipeOptions) == 8, | 39 MOJO_COMPILE_ASSERT(sizeof(MojoCreateMessagePipeOptions) == 8, |
40 MojoCreateMessagePipeOptions_has_wrong_size); | 40 MojoCreateMessagePipeOptions_has_wrong_size); |
41 | 41 |
42 // |MojoWriteMessageFlags|: Used to specify different modes to | 42 // |MojoWriteMessageFlags|: Used to specify different modes to |
43 // |MojoWriteMessage()|. | 43 // |MojoWriteMessage()|. |
44 // |MOJO_WRITE_MESSAGE_FLAG_NONE| - No flags; default mode. | 44 // |MOJO_WRITE_MESSAGE_FLAG_NONE| - No flags; default mode. |
45 | 45 |
46 typedef uint32_t MojoWriteMessageFlags; | 46 typedef uint32_t MojoWriteMessageFlags; |
47 | 47 |
48 #ifdef __cplusplus | 48 #ifdef __cplusplus |
49 const MojoWriteMessageFlags MOJO_WRITE_MESSAGE_FLAG_NONE = 0; | 49 const MojoWriteMessageFlags MOJO_WRITE_MESSAGE_FLAG_NONE = 0; |
50 #else | 50 #else |
51 #define MOJO_WRITE_MESSAGE_FLAG_NONE ((MojoWriteMessageFlags) 0) | 51 #define MOJO_WRITE_MESSAGE_FLAG_NONE ((MojoWriteMessageFlags)0) |
52 #endif | 52 #endif |
53 | 53 |
54 // |MojoReadMessageFlags|: Used to specify different modes to | 54 // |MojoReadMessageFlags|: Used to specify different modes to |
55 // |MojoReadMessage()|. | 55 // |MojoReadMessage()|. |
56 // |MOJO_READ_MESSAGE_FLAG_NONE| - No flags; default mode. | 56 // |MOJO_READ_MESSAGE_FLAG_NONE| - No flags; default mode. |
57 // |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| - If the message is unable to be read | 57 // |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| - If the message is unable to be read |
58 // for whatever reason (e.g., the caller-supplied buffer is too small), | 58 // for whatever reason (e.g., the caller-supplied buffer is too small), |
59 // discard the message (i.e., simply dequeue it). | 59 // discard the message (i.e., simply dequeue it). |
60 | 60 |
61 typedef uint32_t MojoReadMessageFlags; | 61 typedef uint32_t MojoReadMessageFlags; |
62 | 62 |
63 #ifdef __cplusplus | 63 #ifdef __cplusplus |
64 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_NONE = 0; | 64 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_NONE = 0; |
65 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_MAY_DISCARD = 1 << 0; | 65 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_MAY_DISCARD = 1 << 0; |
66 #else | 66 #else |
67 #define MOJO_READ_MESSAGE_FLAG_NONE ((MojoReadMessageFlags) 0) | 67 #define MOJO_READ_MESSAGE_FLAG_NONE ((MojoReadMessageFlags)0) |
68 #define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags) 1 << 0) | 68 #define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags)1 << 0) |
69 #endif | 69 #endif |
70 | 70 |
71 #ifdef __cplusplus | 71 #ifdef __cplusplus |
72 extern "C" { | 72 extern "C" { |
73 #endif | 73 #endif |
74 | 74 |
75 // Note: See the comment in functions.h about the meaning of the "optional" | 75 // Note: See the comment in functions.h about the meaning of the "optional" |
76 // label for pointer parameters. | 76 // label for pointer parameters. |
77 | 77 |
78 // Creates a message pipe, which is a bidirectional communication channel for | 78 // Creates a message pipe, which is a bidirectional communication channel for |
79 // framed data (i.e., messages). Messages can contain plain data and/or Mojo | 79 // framed data (i.e., messages). Messages can contain plain data and/or Mojo |
80 // handles. | 80 // handles. |
81 // | 81 // |
82 // |options| may be set to null for a message pipe with the default options. | 82 // |options| may be set to null for a message pipe with the default options. |
83 // | 83 // |
84 // On success, |*message_pipe_handle0| and |*message_pipe_handle1| are set to | 84 // On success, |*message_pipe_handle0| and |*message_pipe_handle1| are set to |
85 // handles for the two endpoints (ports) for the message pipe. | 85 // handles for the two endpoints (ports) for the message pipe. |
86 // | 86 // |
87 // Returns: | 87 // Returns: |
88 // |MOJO_RESULT_OK| on success. | 88 // |MOJO_RESULT_OK| on success. |
89 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 89 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
90 // |*options| is invalid). | 90 // |*options| is invalid). |
91 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has | 91 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has |
92 // been reached. | 92 // been reached. |
93 // | 93 // |
94 // TODO(vtl): Add an options struct pointer argument. | 94 // TODO(vtl): Add an options struct pointer argument. |
95 MOJO_SYSTEM_EXPORT MojoResult MojoCreateMessagePipe( | 95 MOJO_SYSTEM_EXPORT MojoResult MojoCreateMessagePipe( |
96 const struct MojoCreateMessagePipeOptions* options, // Optional. | 96 const struct MojoCreateMessagePipeOptions* options, // Optional. |
97 MojoHandle* message_pipe_handle0, // Out. | 97 MojoHandle* message_pipe_handle0, // Out. |
98 MojoHandle* message_pipe_handle1); // Out. | 98 MojoHandle* message_pipe_handle1); // Out. |
99 | 99 |
100 // Writes a message to the message pipe endpoint given by |message_pipe_handle|, | 100 // Writes a message to the message pipe endpoint given by |message_pipe_handle|, |
101 // with message data specified by |bytes| of size |num_bytes| and attached | 101 // with message data specified by |bytes| of size |num_bytes| and attached |
102 // handles specified by |handles| of count |num_handles|, and options specified | 102 // handles specified by |handles| of count |num_handles|, and options specified |
103 // by |flags|. If there is no message data, |bytes| may be null, in which case | 103 // by |flags|. If there is no message data, |bytes| may be null, in which case |
104 // |num_bytes| must be zero. If there are no attached handles, |handles| may be | 104 // |num_bytes| must be zero. If there are no attached handles, |handles| may be |
105 // null, in which case |num_handles| must be zero. | 105 // null, in which case |num_handles| must be zero. |
106 // | 106 // |
107 // If handles are attached, on success the handles will no longer be valid (the | 107 // If handles are attached, on success the handles will no longer be valid (the |
108 // receiver will receive equivalent, but logically different, handles). Handles | 108 // receiver will receive equivalent, but logically different, handles). Handles |
109 // to be sent should not be in simultaneous use (e.g., on another thread). | 109 // to be sent should not be in simultaneous use (e.g., on another thread). |
110 // | 110 // |
111 // Returns: | 111 // Returns: |
112 // |MOJO_RESULT_OK| on success (i.e., the message was enqueued). | 112 // |MOJO_RESULT_OK| on success (i.e., the message was enqueued). |
113 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if | 113 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if |
114 // |message_pipe_handle| is not a valid handle, or some of the | 114 // |message_pipe_handle| is not a valid handle, or some of the |
115 // requirements above are not satisfied). | 115 // requirements above are not satisfied). |
116 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if some system limit has been reached, or | 116 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if some system limit has been reached, or |
117 // the number of handles to send is too large (TODO(vtl): reconsider the | 117 // the number of handles to send is too large (TODO(vtl): reconsider the |
118 // latter case). | 118 // latter case). |
119 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. | 119 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. |
120 // Note that closing an endpoint is not necessarily synchronous (e.g., | 120 // Note that closing an endpoint is not necessarily synchronous (e.g., |
121 // across processes), so this function may be succeed even if the other | 121 // across processes), so this function may be succeed even if the other |
122 // endpoint has been closed (in which case the message would be dropped). | 122 // endpoint has been closed (in which case the message would be dropped). |
123 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. | 123 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. |
124 // |MOJO_RESULT_BUSY| if some handle to be sent is currently in use. | 124 // |MOJO_RESULT_BUSY| if some handle to be sent is currently in use. |
125 // | 125 // |
126 // TODO(vtl): Add a notion of capacity for message pipes, and return | 126 // TODO(vtl): Add a notion of capacity for message pipes, and return |
127 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full. | 127 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full. |
128 MOJO_SYSTEM_EXPORT MojoResult MojoWriteMessage( | 128 MOJO_SYSTEM_EXPORT MojoResult |
129 MojoHandle message_pipe_handle, | 129 MojoWriteMessage(MojoHandle message_pipe_handle, |
130 const void* bytes, // Optional. | 130 const void* bytes, // Optional. |
131 uint32_t num_bytes, | 131 uint32_t num_bytes, |
132 const MojoHandle* handles, // Optional. | 132 const MojoHandle* handles, // Optional. |
133 uint32_t num_handles, | 133 uint32_t num_handles, |
134 MojoWriteMessageFlags flags); | 134 MojoWriteMessageFlags flags); |
135 | 135 |
136 // Reads a message from the message pipe endpoint given by | 136 // Reads a message from the message pipe endpoint given by |
137 // |message_pipe_handle|; also usable to query the size of the next message or | 137 // |message_pipe_handle|; also usable to query the size of the next message or |
138 // discard the next message. |bytes|/|*num_bytes| indicate the buffer/buffer | 138 // discard the next message. |bytes|/|*num_bytes| indicate the buffer/buffer |
139 // size to receive the message data (if any) and |handles|/|*num_handles| | 139 // size to receive the message data (if any) and |handles|/|*num_handles| |
140 // indicate the buffer/maximum handle count to receive the attached handles (if | 140 // indicate the buffer/maximum handle count to receive the attached handles (if |
141 // any). | 141 // any). |
142 // | 142 // |
143 // |num_bytes| and |num_handles| are optional "in-out" parameters. If non-null, | 143 // |num_bytes| and |num_handles| are optional "in-out" parameters. If non-null, |
144 // on return |*num_bytes| and |*num_handles| will usually indicate the number | 144 // on return |*num_bytes| and |*num_handles| will usually indicate the number |
(...skipping 12 matching lines...) Expand all Loading... |
157 // Returns: | 157 // Returns: |
158 // |MOJO_RESULT_OK| on success (i.e., a message was actually read). | 158 // |MOJO_RESULT_OK| on success (i.e., a message was actually read). |
159 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid. | 159 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid. |
160 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. | 160 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. |
161 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if one of the buffers to receive the | 161 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if one of the buffers to receive the |
162 // message/attached handles (|bytes|/|*num_bytes| or | 162 // message/attached handles (|bytes|/|*num_bytes| or |
163 // |handles|/|*num_handles|) was too small. (TODO(vtl): Reconsider this | 163 // |handles|/|*num_handles|) was too small. (TODO(vtl): Reconsider this |
164 // error code; should distinguish this from the hitting-system-limits | 164 // error code; should distinguish this from the hitting-system-limits |
165 // case.) | 165 // case.) |
166 // |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read. | 166 // |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read. |
167 MOJO_SYSTEM_EXPORT MojoResult MojoReadMessage( | 167 MOJO_SYSTEM_EXPORT MojoResult |
168 MojoHandle message_pipe_handle, | 168 MojoReadMessage(MojoHandle message_pipe_handle, |
169 void* bytes, // Optional out. | 169 void* bytes, // Optional out. |
170 uint32_t* num_bytes, // Optional in/out. | 170 uint32_t* num_bytes, // Optional in/out. |
171 MojoHandle* handles, // Optional out. | 171 MojoHandle* handles, // Optional out. |
172 uint32_t* num_handles, // Optional in/out. | 172 uint32_t* num_handles, // Optional in/out. |
173 MojoReadMessageFlags flags); | 173 MojoReadMessageFlags flags); |
174 | 174 |
175 #ifdef __cplusplus | 175 #ifdef __cplusplus |
176 } // extern "C" | 176 } // extern "C" |
177 #endif | 177 #endif |
178 | 178 |
179 #endif // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ | 179 #endif // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ |
OLD | NEW |