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 package org.chromium.mojo.system;
6 
7 import java.nio.ByteBuffer;
8 import java.util.List;
9 
10 /**
11  * Message pipes are bidirectional communication channel for framed data (i.e., messages). Messages
12  * can contain plain data and/or Mojo handles.
13  */
14 public interface MessagePipeHandle extends Handle {
15 
16     /**
17      * Flags for the message pipe creation operation.
18      */
19     public static class CreateFlags extends Flags<CreateFlags> {
20         private static final int FLAG_NONE = 0;
21 
22         /**
23          * Immutable flag with not bit set.
24          */
25         public static final CreateFlags NONE = CreateFlags.none().immutable();
26 
27         /**
28          * Dedicated constructor.
29          *
30          * @param flags initial value of the flags.
31          */
CreateFlags(int flags)32         protected CreateFlags(int flags) {
33             super(flags);
34         }
35 
36         /**
37          * @return flags with no bit set.
38          */
none()39         public static CreateFlags none() {
40             return new CreateFlags(FLAG_NONE);
41         }
42 
43     }
44 
45     /**
46      * Used to specify creation parameters for a message pipe to |Core#createMessagePipe()|.
47      */
48     public static class CreateOptions {
49         private CreateFlags mFlags = CreateFlags.NONE;
50 
51         /**
52          * @return the flags
53          */
getFlags()54         public CreateFlags getFlags() {
55             return mFlags;
56         }
57 
58     }
59 
60     /**
61      * Flags for the write operations on MessagePipeHandle .
62      */
63     public static class WriteFlags extends Flags<WriteFlags> {
64         private static final int FLAG_NONE = 0;
65 
66         /**
67          * Immutable flag with no bit set.
68          */
69         public static final WriteFlags NONE = WriteFlags.none().immutable();
70 
71         /**
72          * Dedicated constructor.
73          *
74          * @param flags initial value of the flag.
75          */
WriteFlags(int flags)76         private WriteFlags(int flags) {
77             super(flags);
78         }
79 
80         /**
81          * @return a flag with no bit set.
82          */
none()83         public static WriteFlags none() {
84             return new WriteFlags(FLAG_NONE);
85         }
86     }
87 
88     /**
89      * Flags for the read operations on MessagePipeHandle.
90      */
91     public static class ReadFlags extends Flags<ReadFlags> {
92         private static final int FLAG_NONE = 0;
93 
94         /**
95          * Immutable flag with no bit set.
96          */
97         public static final ReadFlags NONE = ReadFlags.none().immutable();
98 
99         /**
100          * Dedicated constructor.
101          *
102          * @param flags initial value of the flag.
103          */
ReadFlags(int flags)104         private ReadFlags(int flags) {
105             super(flags);
106         }
107 
108         /**
109          * @return a flag with no bit set.
110          */
none()111         public static ReadFlags none() {
112             return new ReadFlags(FLAG_NONE);
113         }
114 
115     }
116 
117     /**
118      * Result of the |readMessage| method.
119      */
120     public static class ReadMessageResult {
121         /**
122          * If a message was read, this contains the bytes of its data.
123          */
124         public byte[] mData;
125         /**
126          * If a message was read, this contains the raw handle values.
127          */
128         public int[] mRawHandles;
129         /**
130          * If a message was read, the handles contained in the message, undefined otherwise.
131          */
132         public List<UntypedHandle> mHandles;
133     }
134 
135     /**
136      * @see org.chromium.mojo.system.Handle#pass()
137      */
138     @Override
pass()139     public MessagePipeHandle pass();
140 
141     /**
142      * Writes a message to the message pipe endpoint, with message data specified by |bytes| and
143      * attached handles specified by |handles|, and options specified by |flags|. If there is no
144      * message data, |bytes| may be null, otherwise it must be a direct ByteBuffer. If there are no
145      * attached handles, |handles| may be null.
146      * <p>
147      * If handles are attached, on success the handles will no longer be valid (the receiver will
148      * receive equivalent, but logically different, handles). Handles to be sent should not be in
149      * simultaneous use (e.g., on another thread).
150      */
writeMessage(ByteBuffer bytes, List<? extends Handle> handles, WriteFlags flags)151     void writeMessage(ByteBuffer bytes, List<? extends Handle> handles, WriteFlags flags);
152 
153     /**
154      * Reads a message from the message pipe endpoint; also usable to query the size of the next
155      * message or discard the next message. |bytes| indicate the buffer/buffer size to receive the
156      * message data (if any) and |maxNumberOfHandles| indicate the maximum handle count to receive
157      * the attached handles (if any). |bytes| is optional. If null, |maxNumberOfHandles| must be
158      * zero, and the return value will indicate the size of the next message. If non-null, it must
159      * be a direct ByteBuffer and the return value will indicate if the message was read or not. If
160      * the message was read its content will be in |bytes|, and the attached handles will be in the
161      * return value. Partial reads are NEVER done. Either a full read is done and |wasMessageRead|
162      * will be true, or the read is NOT done and |wasMessageRead| will be false (if |mayDiscard| was
163      * set, the message is also discarded in this case).
164      */
readMessage(ReadFlags flags)165     ResultAnd<ReadMessageResult> readMessage(ReadFlags flags);
166 }
167