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_SYSTEM_MESSAGE_PIPE_H_ 10 #define MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ 11 12 #include "mojo/public/c/system/macros.h" 13 #include "mojo/public/c/system/system_export.h" 14 #include "mojo/public/c/system/types.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 #ifdef __cplusplus 27 const MojoCreateMessagePipeOptionsFlags 28 MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE = 0; 29 #else 30 #define MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE \ 31 ((MojoCreateMessagePipeOptionsFlags) 0) 32 #endif 33 34 MOJO_COMPILE_ASSERT(MOJO_ALIGNOF(int64_t) == 8, int64_t_has_weird_alignment); 35 struct MOJO_ALIGNAS(8) MojoCreateMessagePipeOptions { 36 uint32_t struct_size; 37 MojoCreateMessagePipeOptionsFlags flags; 38 }; 39 MOJO_COMPILE_ASSERT(sizeof(MojoCreateMessagePipeOptions) == 8, 40 MojoCreateMessagePipeOptions_has_wrong_size); 41 42 // |MojoWriteMessageFlags|: Used to specify different modes to 43 // |MojoWriteMessage()|. 44 // |MOJO_WRITE_MESSAGE_FLAG_NONE| - No flags; default mode. 45 46 typedef uint32_t MojoWriteMessageFlags; 47 48 #ifdef __cplusplus 49 const MojoWriteMessageFlags MOJO_WRITE_MESSAGE_FLAG_NONE = 0; 50 #else 51 #define MOJO_WRITE_MESSAGE_FLAG_NONE ((MojoWriteMessageFlags) 0) 52 #endif 53 54 // |MojoReadMessageFlags|: Used to specify different modes to 55 // |MojoReadMessage()|. 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 58 // for whatever reason (e.g., the caller-supplied buffer is too small), 59 // discard the message (i.e., simply dequeue it). 60 61 typedef uint32_t MojoReadMessageFlags; 62 63 #ifdef __cplusplus 64 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_NONE = 0; 65 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_MAY_DISCARD = 1 << 0; 66 #else 67 #define MOJO_READ_MESSAGE_FLAG_NONE ((MojoReadMessageFlags) 0) 68 #define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags) 1 << 0) 69 #endif 70 71 #ifdef __cplusplus 72 extern "C" { 73 #endif 74 75 // Note: See the comment in functions.h about the meaning of the "optional" 76 // label for pointer parameters. 77 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 80 // handles. 81 // 82 // |options| may be set to null for a message pipe with the default options. 83 // 84 // On success, |*message_pipe_handle0| and |*message_pipe_handle1| are set to 85 // handles for the two endpoints (ports) for the message pipe. 86 // 87 // Returns: 88 // |MOJO_RESULT_OK| on success. 89 // |MOJO_RESULT_INVALID_ARGUMENT| if |message_pipe_handle0| and/or 90 // |message_pipe_handle1| do not appear to be valid pointers. 91 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has 92 // been reached. 93 // 94 // TODO(vtl): Add an options struct pointer argument. 95 MOJO_SYSTEM_EXPORT MojoResult MojoCreateMessagePipe( 96 const struct MojoCreateMessagePipeOptions* options, // Optional. 97 MojoHandle* message_pipe_handle0, // Out. 98 MojoHandle* message_pipe_handle1); // Out. 99 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 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 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. 106 // 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 109 // to be sent should not be in simultaneous use (e.g., on another thread). 110 // 111 // Returns: 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 114 // |message_pipe_handle| is not a valid handle, or some of the 115 // requirements above are not satisfied). 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 118 // latter case). 119 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. 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 122 // endpoint has been closed (in which case the message would be dropped). 123 // |MOJO_RESULT_BUSY| if some handle to be sent is currently in use. 124 // 125 // TODO(vtl): Add a notion of capacity for message pipes, and return 126 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full. 127 MOJO_SYSTEM_EXPORT MojoResult MojoWriteMessage( 128 MojoHandle message_pipe_handle, 129 const void* bytes, // Optional. 130 uint32_t num_bytes, 131 const MojoHandle* handles, // Optional. 132 uint32_t num_handles, 133 MojoWriteMessageFlags flags); 134 135 // Reads a message from the message pipe endpoint given by 136 // |message_pipe_handle|; also usable to query the size of the next message or 137 // discard the next message. |bytes|/|*num_bytes| indicate the buffer/buffer 138 // size to receive the message data (if any) and |handles|/|*num_handles| 139 // indicate the buffer/maximum handle count to receive the attached handles (if 140 // any). 141 // 142 // |num_bytes| and |num_handles| are optional "in-out" parameters. If non-null, 143 // on return |*num_bytes| and |*num_handles| will usually indicate the number 144 // of bytes and number of attached handles in the "next" message, respectively, 145 // whether that message was read or not. (If null, the number of bytes/handles 146 // is treated as zero.) 147 // 148 // If |bytes| is null, then |*num_bytes| must be zero, and similarly for 149 // |handles| and |*num_handles|. 150 // 151 // Partial reads are NEVER done. Either a full read is done and |MOJO_RESULT_OK| 152 // returned, or the read is NOT done and |MOJO_RESULT_RESOURCE_EXHAUSTED| is 153 // returned (if |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| was set, the message is 154 // also discarded in this case). 155 // 156 // Returns: 157 // |MOJO_RESULT_OK| on success (i.e., a message was actually read). 158 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid. 159 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. 160 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if one of the buffers to receive the 161 // message/attached handles (|bytes|/|*num_bytes| or 162 // |handles|/|*num_handles|) was too small. (TODO(vtl): Reconsider this 163 // error code; should distinguish this from the hitting-system-limits 164 // case.) 165 // |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read. 166 MOJO_SYSTEM_EXPORT MojoResult MojoReadMessage( 167 MojoHandle message_pipe_handle, 168 void* bytes, // Optional out. 169 uint32_t* num_bytes, // Optional in/out. 170 MojoHandle* handles, // Optional out. 171 uint32_t* num_handles, // Optional in/out. 172 MojoReadMessageFlags flags); 173 174 #ifdef __cplusplus 175 } // extern "C" 176 #endif 177 178 #endif // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ 179