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 */ 32 protected CreateFlags(int flags) { 33 super(flags); 34 } 35 36 /** 37 * @return flags with no bit set. 38 */ 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 */ 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 */ 76 private WriteFlags(int flags) { 77 super(flags); 78 } 79 80 /** 81 * @return a flag with no bit set. 82 */ 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 private static final int FLAG_MAY_DISCARD = 1 << 0; 94 95 /** 96 * Immutable flag with no bit set. 97 */ 98 public static final ReadFlags NONE = ReadFlags.none().immutable(); 99 100 /** 101 * Dedicated constructor. 102 * 103 * @param flags initial value of the flag. 104 */ 105 private ReadFlags(int flags) { 106 super(flags); 107 } 108 109 /** 110 * Change the may-discard bit of this flag. If set, if the message is unable to be read for 111 * whatever reason (e.g., the caller-supplied buffer is too small), discard the message 112 * (i.e., simply dequeue it). 113 * 114 * @param mayDiscard the new value of the may-discard bit. 115 * @return this. 116 */ 117 public ReadFlags setMayDiscard(boolean mayDiscard) { 118 return setFlag(FLAG_MAY_DISCARD, mayDiscard); 119 } 120 121 /** 122 * @return a flag with no bit set. 123 */ 124 public static ReadFlags none() { 125 return new ReadFlags(FLAG_NONE); 126 } 127 128 } 129 130 /** 131 * Result of the |readMessage| method. 132 */ 133 public static class ReadMessageResult { 134 /** 135 * If a message was read, the size in bytes of the message, otherwise the size in bytes of 136 * the next message. 137 */ 138 private int mMessageSize; 139 /** 140 * If a message was read, the number of handles contained in the message, otherwise the 141 * number of handles contained in the next message. 142 */ 143 private int mHandlesCount; 144 /** 145 * If a message was read, the handles contained in the message, undefined otherwise. 146 */ 147 private List<UntypedHandle> mHandles; 148 149 /** 150 * @return the messageSize 151 */ 152 public int getMessageSize() { 153 return mMessageSize; 154 } 155 156 /** 157 * @param messageSize the messageSize to set 158 */ 159 public void setMessageSize(int messageSize) { 160 mMessageSize = messageSize; 161 } 162 163 /** 164 * @return the handlesCount 165 */ 166 public int getHandlesCount() { 167 return mHandlesCount; 168 } 169 170 /** 171 * @param handlesCount the handlesCount to set 172 */ 173 public void setHandlesCount(int handlesCount) { 174 mHandlesCount = handlesCount; 175 } 176 177 /** 178 * @return the handles 179 */ 180 public List<UntypedHandle> getHandles() { 181 return mHandles; 182 } 183 184 /** 185 * @param handles the handles to set 186 */ 187 public void setHandles(List<UntypedHandle> handles) { 188 mHandles = handles; 189 } 190 } 191 192 /** 193 * @see org.chromium.mojo.system.Handle#pass() 194 */ 195 @Override 196 public MessagePipeHandle pass(); 197 198 /** 199 * Writes a message to the message pipe endpoint, with message data specified by |bytes| and 200 * attached handles specified by |handles|, and options specified by |flags|. If there is no 201 * message data, |bytes| may be null, otherwise it must be a direct ByteBuffer. If there are no 202 * attached handles, |handles| may be null. 203 * <p> 204 * If handles are attached, on success the handles will no longer be valid (the receiver will 205 * receive equivalent, but logically different, handles). Handles to be sent should not be in 206 * simultaneous use (e.g., on another thread). 207 */ 208 void writeMessage(ByteBuffer bytes, List<? extends Handle> handles, WriteFlags flags); 209 210 /** 211 * Reads a message from the message pipe endpoint; also usable to query the size of the next 212 * message or discard the next message. |bytes| indicate the buffer/buffer size to receive the 213 * message data (if any) and |maxNumberOfHandles| indicate the maximum handle count to receive 214 * the attached handles (if any). |bytes| is optional. If null, |maxNumberOfHandles| must be 215 * zero, and the return value will indicate the size of the next message. If non-null, it must 216 * be a direct ByteBuffer and the return value will indicate if the message was read or not. If 217 * the message was read its content will be in |bytes|, and the attached handles will be in the 218 * return value. Partial reads are NEVER done. Either a full read is done and |wasMessageRead| 219 * will be true, or the read is NOT done and |wasMessageRead| will be false (if |mayDiscard| was 220 * set, the message is also discarded in this case). 221 */ 222 ResultAnd<ReadMessageResult> readMessage( 223 ByteBuffer bytes, int maxNumberOfHandles, ReadFlags flags); 224 } 225
