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
5package org.chromium.mojo.system;
6
7import java.nio.ByteBuffer;
8
9/**
10 * A buffer that can be shared between applications.
11 */
12public interface SharedBufferHandle extends Handle {
13
14    /**
15     * Flags for the shared buffer creation operation.
16     */
17    public static class CreateFlags extends Flags<CreateFlags> {
18        private static final int FLAG_NONE = 0;
19
20        /**
21         * Immutable flag with not bit set.
22         */
23        public static final CreateFlags NONE = CreateFlags.none().immutable();
24
25        /**
26         * Dedicated constructor.
27         *
28         * @param flags initial value of the flags.
29         */
30        protected CreateFlags(int flags) {
31            super(flags);
32        }
33
34        /**
35         * @return flags with no bit set.
36         */
37        public static CreateFlags none() {
38            return new CreateFlags(FLAG_NONE);
39        }
40
41    }
42
43    /**
44     * Used to specify creation parameters for a shared buffer to |Core#createSharedBuffer()|.
45     */
46    public static class CreateOptions {
47        private CreateFlags mFlags = CreateFlags.NONE;
48
49        /**
50         * @return the flags
51         */
52        public CreateFlags getFlags() {
53            return mFlags;
54        }
55
56    }
57
58    /**
59     * Flags for the shared buffer duplication operation.
60     */
61    public static class DuplicateFlags extends Flags<DuplicateFlags> {
62        private static final int FLAG_NONE = 0;
63
64        /**
65         * Immutable flag with not bit set.
66         */
67        public static final DuplicateFlags NONE = DuplicateFlags.none().immutable();
68
69        /**
70         * Dedicated constructor.
71         *
72         * @param flags initial value of the flags.
73         */
74        protected DuplicateFlags(int flags) {
75            super(flags);
76        }
77
78        /**
79         * @return flags with no bit set.
80         */
81        public static DuplicateFlags none() {
82            return new DuplicateFlags(FLAG_NONE);
83        }
84
85    }
86
87    /**
88     * Used to specify parameters in duplicating access to a shared buffer to
89     * |SharedBufferHandle#duplicate|
90     */
91    public static class DuplicateOptions {
92        private DuplicateFlags mFlags = DuplicateFlags.NONE;
93
94        /**
95         * @return the flags
96         */
97        public DuplicateFlags getFlags() {
98            return mFlags;
99        }
100
101    }
102
103    /**
104     * Flags for the shared buffer map operation.
105     */
106    public static class MapFlags extends Flags<MapFlags> {
107        private static final int FLAG_NONE = 0;
108
109        /**
110         * Immutable flag with not bit set.
111         */
112        public static final MapFlags NONE = MapFlags.none().immutable();
113
114        /**
115         * Dedicated constructor.
116         *
117         * @param flags initial value of the flags.
118         */
119        protected MapFlags(int flags) {
120            super(flags);
121        }
122
123        /**
124         * @return flags with no bit set.
125         */
126        public static MapFlags none() {
127            return new MapFlags(FLAG_NONE);
128        }
129
130    }
131
132    /**
133     * @see org.chromium.mojo.system.Handle#pass()
134     */
135    @Override
136    public SharedBufferHandle pass();
137
138    /**
139     * Duplicates the handle. This creates another handle (returned on success), which can then be
140     * sent to another application over a message pipe, while retaining access to this handle (and
141     * any mappings that it may have).
142     */
143    public SharedBufferHandle duplicate(DuplicateOptions options);
144
145    /**
146     * Map the part (at offset |offset| of length |numBytes|) of the buffer given by this handle
147     * into memory. |offset + numBytes| must be less than or equal to the size of the buffer. On
148     * success, the returned buffer points to memory with the requested part of the buffer. A single
149     * buffer handle may have multiple active mappings (possibly depending on the buffer type). The
150     * permissions (e.g., writable or executable) of the returned memory may depend on the
151     * properties of the buffer and properties attached to the buffer handle as well as |flags|.
152     */
153    public ByteBuffer map(long offset, long numBytes, MapFlags flags);
154
155    /**
156     * Unmap a buffer pointer that was mapped by |map()|.
157     */
158    public void unmap(ByteBuffer buffer);
159
160}
161