src/mojo/public/java/system/src/org/chromium/mojo/system/MessagePipeHandle.java

   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          * The MojoResult value of the read call.
 136          */
 137         private int mMojoResult;
 138         /**
 139          * If a message was read, the size in bytes of the message, otherwise the size in bytes of
 140          * the next message.
 141          */
 142         private int mMessageSize;
 143         /**
 144          * If a message was read, the number of handles contained in the message, otherwise the
 145          * number of handles contained in the next message.
 146          */
 147         private int mHandlesCount;
 148         /**
 149          * If a message was read, the handles contained in the message, undefined otherwise.
 150          */
 151         private List<UntypedHandle> mHandles;
 152
 153         /**
 154          * @return the mojoResult
 155          */
 156         public int getMojoResult() {
 157             return mMojoResult;
 158         }
 159
 160         /**
 161          * @param mojoResult the mojoResult to set
 162          */
 163         public void setMojoResult(int mojoResult) {
 164             mMojoResult = mojoResult;
 165         }
 166
 167         /**
 168          * @return the messageSize
 169          */
 170         public int getMessageSize() {
 171             return mMessageSize;
 172         }
 173
 174         /**
 175          * @param messageSize the messageSize to set
 176          */
 177         public void setMessageSize(int messageSize) {
 178             mMessageSize = messageSize;
 179         }
 180
 181         /**
 182          * @return the handlesCount
 183          */
 184         public int getHandlesCount() {
 185             return mHandlesCount;
 186         }
 187
 188         /**
 189          * @param handlesCount the handlesCount to set
 190          */
 191         public void setHandlesCount(int handlesCount) {
 192             mHandlesCount = handlesCount;
 193         }
 194
 195         /**
 196          * @return the handles
 197          */
 198         public List<UntypedHandle> getHandles() {
 199             return mHandles;
 200         }
 201
 202         /**
 203          * @param handles the handles to set
 204          */
 205         public void setHandles(List<UntypedHandle> handles) {
 206             mHandles = handles;
 207         }
 208     }
 209
 210     /**
 211      * @see org.chromium.mojo.system.Handle#pass()
 212      */
 213     @Override
 214     public MessagePipeHandle pass();
 215
 216     /**
 217      * Writes a message to the message pipe endpoint, with message data specified by |bytes| and
 218      * attached handles specified by |handles|, and options specified by |flags|. If there is no
 219      * message data, |bytes| may be null, otherwise it must be a direct ByteBuffer. If there are no
 220      * attached handles, |handles| may be null.
 221      * <p>
 222      * If handles are attached, on success the handles will no longer be valid (the receiver will
 223      * receive equivalent, but logically different, handles). Handles to be sent should not be in
 224      * simultaneous use (e.g., on another thread).
 225      */
 226     void writeMessage(ByteBuffer bytes, List<? extends Handle> handles, WriteFlags flags);
 227
 228     /**
 229      * Reads a message from the message pipe endpoint; also usable to query the size of the next
 230      * message or discard the next message. |bytes| indicate the buffer/buffer size to receive the
 231      * message data (if any) and |maxNumberOfHandles| indicate the maximum handle count to receive
 232      * the attached handles (if any). |bytes| is optional. If null, |maxNumberOfHandles| must be
 233      * zero, and the return value will indicate the size of the next message. If non-null, it must
 234      * be a direct ByteBuffer and the return value will indicate if the message was read or not. If
 235      * the message was read its content will be in |bytes|, and the attached handles will be in the
 236      * return value. Partial reads are NEVER done. Either a full read is done and |wasMessageRead|
 237      * will be true, or the read is NOT done and |wasMessageRead| will be false (if |mayDiscard| was
 238      * set, the message is also discarded in this case).
 239      */
 240     ReadMessageResult readMessage(ByteBuffer bytes, int maxNumberOfHandles,
 241             ReadFlags flags);
 242 }