summaryrefslogtreecommitdiff
path: root/src/lib/efl/interfaces/efl_io_buffer.eo
blob: 89bb92b71cb15c47ecfd72cd90b71ff1ae1a088b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
class Efl.Io.Buffer (Efl.Object, Efl.Io.Reader, Efl.Io.Writer, Efl.Io.Closer, Efl.Io.Sizer, Efl.Io.Positioner) {
    [[Generic In-memory buffer of data to be used as I/O.

      This class offers both input and output, which can be used at
      the same time since @Efl.Io.Reader.read and @Efl.Io.Writer.write
      use different offsets/position internally.

      One can get temporary direct access to internal buffer with
      @.slice_get or steal the buffer with @.binbuf_steal.

      A fixed sized buffer can be implemented by setting @.limit
      followed by @.preallocate

      @since 1.19
    ]]

    methods {
        preallocate {
            [[Immediately pre-allocate a buffer of at least a given size.]]
            params {
                @in size: size; [[amount of bytes to pre-allocate.]]
            }
        }

        @property limit {
            [[Limit how big the buffer can grow.

              This affects both @.preallocate and how buffer grows
              when @Efl.Io.Writer.write is called.

              If you want a buffer of an exact size, always set the
              limit before any further calls that can grow it.
            ]]
            get { }
            set {
                [[Constructor-only property to set buffer limit. 0 is unlimited]]
            }
            values {
                size: size; [[Defines a maximum buffer size, or 0 to allow unlimited amount of bytes]]
            }
        }

        @property position_read {
            [[The position used by @Efl.Io.Reader.read.

             Note that @Efl.Io.Positioner.seek or
             @Efl.Io.Positioner.position.set will affect this property
             and @.position_write.

             @Efl.Io.Positioner.position.get will return the greatest
             of @.position_read and @.position_write.
            ]]
            get { }
            set {
                return: bool (false);
            }
            values {
                position: uint64;
            }
        }

        @property position_write {
            [[The position used by @Efl.Io.Writer.write.

             Note that @Efl.Io.Positioner.seek or
             @Efl.Io.Positioner.position.set will affect this property
             and @.position_read.

             @Efl.Io.Positioner.position.get will return the greatest
             of @.position_read and @.position_write.
            ]]
            get { }
            set {
                return: bool (false);
            }
            values {
                position: uint64;
            }
        }

        slice_get { // TODO: property and return of Eina.Slice (not pointer)
            [[Get a temporary access to buffer's internal memory.

              The memory pointed by slice may be changed by other
              methods of this class. The event "reallocated" will be
              called in those situations.
            ]]
            params {
                @out slice: Eina.Slice; [[slice of the current buffer, may be invalidated if @Efl.Io.Writer.write, @Efl.Io.Closer.close or @Efl.Io.Sizer.resize are called. It is the full slice, not a partial one starting at current position.]]
            }
            return: bool (false);
        }

        binbuf_steal {
            [[Steals the internal buffer memory and returns it as a binbuf.

              The returned memory must be freed with eina_binbuf_free().
            ]]
            return: free(own(Eina.Binbuf*), eina_binbuf_free) @warn_unused;
        }
    }

    events {
       position_read,changed; [[Notifies @.position_read changed]]
       position_write,changed; [[Notifies @.position_write changed]]
       reallocated; [[Notifies the internal buffer was reallocated, thus whatever was returned by @.slice_get becomes invalid]]
    }

    implements {
        Efl.Object.finalize;
        Efl.Object.destructor;
        Efl.Io.Reader.read;
        Efl.Io.Reader.can_read.get;
        Efl.Io.Reader.can_read.set;
        Efl.Io.Reader.eos.get;
        Efl.Io.Reader.eos.set;
        Efl.Io.Writer.write;
        Efl.Io.Writer.can_write.get;
        Efl.Io.Writer.can_write.set;
        Efl.Io.Closer.close;
        Efl.Io.Closer.closed.get;
        Efl.Io.Sizer.resize;
        Efl.Io.Sizer.size.get;
        Efl.Io.Positioner.seek;
        Efl.Io.Positioner.position.get;
    }
}