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 * Flags for the write operations on MessagePipeHandle . 17 */ 18 public static class WriteFlags extends Flags<WriteFlags> { 19 private static final int FLAG_NONE = 0; 20 21 /** 22 * Immutable flag with no bit set. 23 */ 24 public static final WriteFlags NONE = WriteFlags.none().immutable(); 25 26 /** 27 * Dedicated constructor. 28 * 29 * @param flags initial value of the flag. 30 */ WriteFlags(int flags)31 private WriteFlags(int flags) { 32 super(flags); 33 } 34 35 /** 36 * @return a flag with no bit set. 37 */ none()38 public static WriteFlags none() { 39 return new WriteFlags(FLAG_NONE); 40 } 41 } 42 43 /** 44 * Flags for the read operations on MessagePipeHandle. 45 */ 46 public static class ReadFlags extends Flags<ReadFlags> { 47 private static final int FLAG_NONE = 0; 48 private static final int FLAG_MAY_DISCARD = 1 << 0; 49 50 /** 51 * Immutable flag with no bit set. 52 */ 53 public static final ReadFlags NONE = ReadFlags.none().immutable(); 54 55 /** 56 * Dedicated constructor. 57 * 58 * @param flags initial value of the flag. 59 */ ReadFlags(int flags)60 private ReadFlags(int flags) { 61 super(flags); 62 } 63 64 /** 65 * Change the may-discard bit of this flag. If set, if the message is unable to be read for 66 * whatever reason (e.g., the caller-supplied buffer is too small), discard the message 67 * (i.e., simply dequeue it). 68 * 69 * @param mayDiscard the new value of the may-discard bit. 70 * @return this. 71 */ setMayDiscard(boolean mayDiscard)72 public ReadFlags setMayDiscard(boolean mayDiscard) { 73 return setFlag(FLAG_MAY_DISCARD, mayDiscard); 74 } 75 76 /** 77 * @return a flag with no bit set. 78 */ none()79 public static ReadFlags none() { 80 return new ReadFlags(FLAG_NONE); 81 } 82 83 } 84 85 /** 86 * Writes a message to the message pipe endpoint, with message data specified by |bytes| and 87 * attached handles specified by |handles|, and options specified by |flags|. If there is no 88 * message data, |bytes| may be null, otherwise it must be a direct ByteBuffer. If there are no 89 * attached handles, |handles| may be null. 90 * <p> 91 * If handles are attached, on success the handles will no longer be valid (the receiver will 92 * receive equivalent, but logically different, handles). Handles to be sent should not be in 93 * simultaneous use (e.g., on another thread). 94 */ writeMessage(ByteBuffer bytes, List<? extends Handle> handles, WriteFlags flags)95 void writeMessage(ByteBuffer bytes, List<? extends Handle> handles, WriteFlags flags); 96 97 /** 98 * Result of the |readMessage| method. 99 */ 100 public static class ReadMessageResult { 101 /** 102 * The MojoResult value of the read call. 103 */ 104 private int mMojoResult; 105 /** 106 * If a message was read, the size in bytes of the message, otherwise the size in bytes of 107 * the next message. 108 */ 109 private int mMessageSize; 110 /** 111 * If a message was read, the number of handles contained in the message, otherwise the 112 * number of handles contained in the next message. 113 */ 114 private int mHandlesCount; 115 /** 116 * If a message was read, the handles contained in the message, undefined otherwise. 117 */ 118 private List<UntypedHandle> mHandles; 119 120 /** 121 * @return the mojoResult 122 */ getMojoResult()123 public int getMojoResult() { 124 return mMojoResult; 125 } 126 127 /** 128 * @param mojoResult the mojoResult to set 129 */ setMojoResult(int mojoResult)130 public void setMojoResult(int mojoResult) { 131 mMojoResult = mojoResult; 132 } 133 134 /** 135 * @return the messageSize 136 */ getMessageSize()137 public int getMessageSize() { 138 return mMessageSize; 139 } 140 141 /** 142 * @param messageSize the messageSize to set 143 */ setMessageSize(int messageSize)144 public void setMessageSize(int messageSize) { 145 mMessageSize = messageSize; 146 } 147 148 /** 149 * @return the handlesCount 150 */ getHandlesCount()151 public int getHandlesCount() { 152 return mHandlesCount; 153 } 154 155 /** 156 * @param handlesCount the handlesCount to set 157 */ setHandlesCount(int handlesCount)158 public void setHandlesCount(int handlesCount) { 159 mHandlesCount = handlesCount; 160 } 161 162 /** 163 * @return the handles 164 */ getHandles()165 public List<UntypedHandle> getHandles() { 166 return mHandles; 167 } 168 169 /** 170 * @param handles the handles to set 171 */ setHandles(List<UntypedHandle> handles)172 public void setHandles(List<UntypedHandle> handles) { 173 mHandles = handles; 174 } 175 } 176 177 /** 178 * Reads a message from the message pipe endpoint; also usable to query the size of the next 179 * message or discard the next message. |bytes| indicate the buffer/buffer size to receive the 180 * message data (if any) and |maxNumberOfHandles| indicate the maximum handle count to receive 181 * the attached handles (if any). |bytes| is optional. If null, |maxNumberOfHandles| must be 182 * zero, and the return value will indicate the size of the next message. If non-null, it must 183 * be a direct ByteBuffer and the return value will indicate if the message was read or not. If 184 * the message was read its content will be in |bytes|, and the attached handles will be in the 185 * return value. Partial reads are NEVER done. Either a full read is done and |wasMessageRead| 186 * will be true, or the read is NOT done and |wasMessageRead| will be false (if |mayDiscard| was 187 * set, the message is also discarded in this case). 188 */ readMessage(ByteBuffer bytes, int maxNumberOfHandles, ReadFlags flags)189 ReadMessageResult readMessage(ByteBuffer bytes, int maxNumberOfHandles, 190 ReadFlags flags); 191 } 192