Home | History | Annotate | Download | only in system 
      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 
     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          */
    104         private ReadFlags(int flags) {
    105             super(flags);
    106         }
    107 
    108         /**
    109          * @return a flag with no bit set.
    110          */
    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
    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      */
    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      */
    165     ResultAnd<ReadMessageResult> readMessage(ReadFlags flags);
    166 }
    167