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