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