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// Module "mojo/public/js/bindings/core"
6//
7// Note: This file is for documentation purposes only. The code here is not
8// actually executed. The real module is implemented natively in Mojo.
9//
10// This module provides the JavaScript bindings for mojo/public/c/system/core.h.
11// Refer to that file for more detailed documentation for equivalent methods.
12
13while (1);
14
15/**
16 * MojoHandle: An opaque handles to a Mojo object (e.g. a message pipe).
17 */
18var kInvalidHandle;
19
20/**
21 * MojoResult {number}: Result codes for Mojo operations.
22 * See core.h for more information.
23 */
24var RESULT_OK;
25var RESULT_CANCELLED;
26var RESULT_UNKNOWN;
27var RESULT_INVALID_ARGUMENT;
28var RESULT_DEADLINE_EXCEEDED;
29var RESULT_NOT_FOUND;
30var RESULT_ALREADY_EXISTS;
31var RESULT_PERMISSION_DENIED;
32var RESULT_RESOURCE_EXHAUSTED;
33var RESULT_FAILED_PRECONDITION;
34var RESULT_ABORTED;
35var RESULT_OUT_OF_RANGE;
36var RESULT_UNIMPLEMENTED;
37var RESULT_INTERNAL;
38var RESULT_UNAVAILABLE;
39var RESULT_DATA_LOSS;
40var RESULT_BUSY;
41var RESULT_SHOULD_WAIT;
42
43/**
44 * MojoDeadline {number}: Used to specify deadlines (timeouts), in microseconds.
45 * See core.h for more information.
46 */
47var DEADLINE_INDEFINITE;
48
49/**
50 * MojoHandleSignals: Used to specify signals that can be waited on for a handle
51 *(and which can be triggered), e.g., the ability to read or write to
52 * the handle.
53 * See core.h for more information.
54 */
55var HANDLE_SIGNAL_NONE;
56var HANDLE_SIGNAL_READABLE;
57var HANDLE_SIGNAL_WRITABLE;
58
59/**
60 * MojoCreateDataMessageOptions: Used to specify creation parameters for a data
61 * pipe to |createDataMessage()|.
62 * See core.h for more information.
63 */
64dictionary MojoCreateDataMessageOptions {
65  MojoCreateDataMessageOptionsFlags flags;  // See below.
66};
67
68// MojoCreateDataMessageOptionsFlags
69var CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE;
70
71/*
72 * MojoWriteMessageFlags: Used to specify different modes to |writeMessage()|.
73 * See core.h for more information.
74 */
75var WRITE_MESSAGE_FLAG_NONE;
76
77/**
78 * MojoReadMessageFlags: Used to specify different modes to |readMessage()|.
79 * See core.h for more information.
80 */
81var READ_MESSAGE_FLAG_NONE;
82var READ_MESSAGE_FLAG_MAY_DISCARD;
83
84/**
85 * MojoCreateDataPipeOptions: Used to specify creation parameters for a data
86 * pipe to |createDataPipe()|.
87 * See core.h for more information.
88 */
89dictionary MojoCreateDataPipeOptions {
90  MojoCreateDataPipeOptionsFlags flags;  // See below.
91  int32 elementNumBytes;  // The size of an element, in bytes.
92  int32 capacityNumBytes;  // The capacity of the data pipe, in bytes.
93};
94
95// MojoCreateDataPipeOptionsFlags
96var CREATE_DATA_PIPE_OPTIONS_FLAG_NONE;
97var CREATE_DATA_PIPE_OPTIONS_FLAG_MAY_DISCARD;
98
99/*
100 * MojoWriteDataFlags: Used to specify different modes to |writeData()|.
101 * See core.h for more information.
102 */
103var WRITE_DATA_FLAG_NONE;
104var WRITE_DATA_FLAG_ALL_OR_NONE;
105
106/**
107 * MojoReadDataFlags: Used to specify different modes to |readData()|.
108 * See core.h for more information.
109 */
110var READ_DATA_FLAG_NONE;
111var READ_DATA_FLAG_ALL_OR_NONE;
112var READ_DATA_FLAG_DISCARD;
113var READ_DATA_FLAG_QUERY;
114
115/**
116 * Closes the given |handle|. See MojoClose for more info.
117 * @param {MojoHandle} Handle to close.
118 * @return {MojoResult} Result code.
119 */
120function close(handle) { [native code] }
121
122/**
123 * Waits on the given handle until a signal indicated by |signals| is
124 * satisfied or until |deadline| is passed. See MojoWait for more information.
125 *
126 * @param {MojoHandle} handle Handle to wait on.
127 * @param {MojoHandleSignals} signals Specifies the condition to wait for.
128 * @param {MojoDeadline} deadline Stops waiting if this is reached.
129 * @return {MojoResult} Result code.
130 */
131function wait(handle, signals, deadline) { [native code] }
132
133/**
134 * Waits on |handles[0]|, ..., |handles[handles.length-1]| for at least one of
135 * them to satisfy the state indicated by |flags[0]|, ...,
136 * |flags[handles.length-1]|, respectively, or until |deadline| has passed.
137 * See MojoWaitMany for more information.
138 *
139 * @param {Array.MojoHandle} handles Handles to wait on.
140 * @param {Array.MojoHandleSignals} signals Specifies the condition to wait for,
141 *   for each corresponding handle. Must be the same length as |handles|.
142 * @param {MojoDeadline} deadline Stops waiting if this is reached.
143 * @return {MojoResult} Result code.
144 */
145function waitMany(handles, signals, deadline) { [native code] }
146
147/**
148 * Creates a message pipe. This function always succeeds.
149 * See MojoCreateMessagePipe for more information on message pipes.
150 *
151 * @param {MojoCreateMessagePipeOptions} optionsDict Options to control the
152 * message pipe parameters. May be null.
153 * @return {MessagePipe} An object of the form {
154 *     handle0,
155 *     handle1,
156 *   }
157 *   where |handle0| and |handle1| are MojoHandles to each end of the channel.
158 */
159function createMessagePipe(optionsDict) { [native code] }
160
161/**
162 * Writes a message to the message pipe endpoint given by |handle|. See
163 * MojoWriteMessage for more information, including return codes.
164 *
165 * @param {MojoHandle} handle The endpoint to write to.
166 * @param {ArrayBufferView} buffer The message data. May be empty.
167 * @param {Array.MojoHandle} handlesArray Any handles to attach. Handles are
168 *   transferred on success and will no longer be valid. May be empty.
169 * @param {MojoWriteMessageFlags} flags Flags.
170 * @return {MojoResult} Result code.
171 */
172function writeMessage(handle, buffer, handlesArray, flags) { [native code] }
173
174/**
175 * Reads a message from the message pipe endpoint given by |handle|. See
176 * MojoReadMessage for more information, including return codes.
177 *
178 * @param {MojoHandle} handle The endpoint to read from.
179 * @param {MojoReadMessageFlags} flags Flags.
180 * @return {object} An object of the form {
181 *     result,  // |RESULT_OK| on success, error code otherwise.
182 *     buffer,  // An ArrayBufferView of the message data (only on success).
183 *     handles  // An array of MojoHandles transferred, if any.
184 *   }
185 */
186function readMessage(handle, flags) { [native code] }
187
188/**
189 * Creates a data pipe, which is a unidirectional communication channel for
190 * unframed data, with the given options. See MojoCreateDataPipe for more
191 * more information, including return codes.
192 *
193 * @param {MojoCreateDataPipeOptions} optionsDict Options to control the data
194 *   pipe parameters. May be null.
195 * @return {object} An object of the form {
196 *     result,  // |RESULT_OK| on success, error code otherwise.
197 *     producerHandle,  // MojoHandle to use with writeData (only on success).
198 *     consumerHandle,  // MojoHandle to use with readData (only on success).
199 *   }
200 */
201function createDataPipe(optionsDict) { [native code] }
202
203/**
204 * Writes the given data to the data pipe producer given by |handle|. See
205 * MojoWriteData for more information, including return codes.
206 *
207 * @param {MojoHandle} handle A producerHandle returned by createDataPipe.
208 * @param {ArrayBufferView} buffer The data to write.
209 * @param {MojoWriteDataFlags} flags Flags.
210 * @return {object} An object of the form {
211 *     result,  // |RESULT_OK| on success, error code otherwise.
212 *     numBytes,  // The number of bytes written.
213 *   }
214 */
215function writeData(handle, buffer, flags) { [native code] }
216
217/**
218 * Reads data from the data pipe consumer given by |handle|. May also
219 * be used to discard data. See MojoReadData for more information, including
220 * return codes.
221 *
222 * @param {MojoHandle} handle A consumerHandle returned by createDataPipe.
223 * @param {MojoReadDataFlags} flags Flags.
224 * @return {object} An object of the form {
225 *     result,  // |RESULT_OK| on success, error code otherwise.
226 *     buffer,  // An ArrayBufferView of the data read (only on success).
227 *   }
228 */
229function readData(handle, flags) { [native code] }
230