summaryrefslogtreecommitdiff
path: root/pages/develop/api/efl/net/socket/simple.txt
blob: 74b04b4d81fc181b6eeb5de8ba1fe998a2569115 (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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
~~Title: Efl.Net.Socket.Simple~~
====== Efl.Net.Socket.Simple (class) ======

===== Description =====

%%A wrapper socket offering an easy to use, buffered I/O.%%

%%The simple socket encapsulates an actual %%[[:develop:api:efl:net:socket|Efl.Net.Socket]]%% and uses it with an %%[[:develop:api:efl:io:buffered_stream|Efl.Io.Buffered_Stream]]%%, which creates an input %%[[:develop:api:efl:io:queue|Efl.Io.Queue]]%% and an output %%[[:develop:api:efl:io:queue|Efl.Io.Queue]]%%. These are linked using a receiver and a sender %%[[:develop:api:efl:io:copier|Efl.Io.Copier]]%%.%%

%%The idea is that unlike the traditional %%[[:develop:api:efl:net:socket|Efl.Net.Socket]]%% which attempts to write directly to socket and thus may take less data than requested, this one will keep the pending data in its own buffer, feeding to the actual socket when %%[[:develop:api:efl:io:writer:property:can_write|Efl.Io.Writer.can_write]]%%. This makes its operation much simpler as %%[[:develop:api:efl:io:writer:method:write|Efl.Io.Writer.write]]%% will always take the full data -- allows "write and forget", if unlimited (see %%[[:develop:api:efl:io:buffered_stream:property:max_queue_size_output|Efl.Io.Buffered_Stream.max_queue_size_output]]%%).%%

%%Reading is also much simpler since received data is kept in an %%[[:develop:api:efl:io:queue|Efl.Io.Queue]]%%, thus its size can be queried with %%[[:develop:api:efl:io:buffered_stream:property:pending_read|Efl.Io.Buffered_Stream.pending_read]]%% and read with %%[[:develop:api:efl:io:reader:method:read|Efl.Io.Reader.read]]%% or peeked with %%[[:develop:api:efl:io:buffered_stream:property:slice|Efl.Io.Buffered_Stream.slice]]%%, then discarded with %%[[:develop:api:efl:io:buffered_stream:method:discard|Efl.Io.Buffered_Stream.discard]]%% or %%[[:develop:api:efl:io:buffered_stream:method:clear|Efl.Io.Buffered_Stream.clear]]%%.%%

%%When waiting for a complete message, you can just peek at its contents: if incomplete do nothing, if complete then use either %%[[:develop:api:efl:io:reader:method:read|Efl.Io.Reader.read]]%% to get a copy or manipulate a read-only reference from %%[[:develop:api:efl:io:buffered_stream:property:slice|Efl.Io.Buffered_Stream.slice]]%% and then %%[[:develop:api:efl:io:buffered_stream:method:discard|Efl.Io.Buffered_Stream.discard]]%%%%

%%The actual socket is set with the constructor method %%[[:develop:api:efl:io:buffered_stream:property:inner_io|Efl.Io.Buffered_Stream.inner_io.set]]%% and can be retrieved with %%[[:develop:api:efl:io:buffered_stream:property:inner_io|Efl.Io.Buffered_Stream.inner_io.get]]%%, which should be used with care.%%

//Since 1.19//

{{page>:develop:api-include:efl:net:socket:simple:description&nouser&nolink&nodate}}

===== Inheritance =====

 => [[:develop:api:efl:io:buffered_stream|Efl.Io.Buffered_Stream]] //(class)// => [[:develop:api:efl:loop:consumer|Efl.Loop.Consumer]] //(class)// => [[:develop:api:efl:object|Efl.Object]] //(class)//
++++ Full hierarchy |

  * [[:develop:api:efl:io:buffered_stream|Efl.Io.Buffered_Stream]] //(class)//
    * [[:develop:api:efl:loop:consumer|Efl.Loop.Consumer]] //(class)//
      * [[:develop:api:efl:object|Efl.Object]] //(class)//
    * [[:develop:api:efl:io:reader|Efl.Io.Reader]] //(interface)//
    * [[:develop:api:efl:io:writer|Efl.Io.Writer]] //(interface)//
    * [[:develop:api:efl:io:closer|Efl.Io.Closer]] //(mixin)//
  * [[:develop:api:efl:net:socket|Efl.Net.Socket]] //(interface)//
    * [[:develop:api:efl:io:reader|Efl.Io.Reader]] //(interface)//
    * [[:develop:api:efl:io:writer|Efl.Io.Writer]] //(interface)//
    * [[:develop:api:efl:io:closer|Efl.Io.Closer]] //(mixin)//


++++
===== Members =====

**[[:develop:api:efl:net:socket:simple:property:address_local|address_local]]** //**(get, set)**// ''protected set''// [Overridden from [[:develop:api:efl:net:socket|Efl.Net.Socket]]]//\\
> %%The local address, similar to getsockname().%%
<code c>
const char *efl_net_socket_address_local_get(const Eo *obj);
void efl_net_socket_address_local_set(Eo *obj, const char *address);
</code>
\\
**[[:develop:api:efl:net:socket:simple:property:address_remote|address_remote]]** //**(get, set)**// ''protected set''// [Overridden from [[:develop:api:efl:net:socket|Efl.Net.Socket]]]//\\
> %%The remote address, similar to getpeername().%%
<code c>
const char *efl_net_socket_address_remote_get(const Eo *obj);
void efl_net_socket_address_remote_set(Eo *obj, const char *address);
</code>
\\
**[[:develop:api:efl:net:socket:simple:property:inner_io|inner_io]]** //**(get, set)**//// [Overridden from [[:develop:api:efl:io:buffered_stream|Efl.Io.Buffered_Stream]]]//\\
> %%The inner I/O this wrapper operates on.%%
<code c>
Efl_Object *efl_io_buffered_stream_inner_io_get(const Eo *obj);
void efl_io_buffered_stream_inner_io_set(Eo *obj, Efl_Object *io);
</code>
\\

==== Inherited ====

^ [[:develop:api:efl:io:buffered_stream|Efl.Io.Buffered_Stream]] ^^^
|  ''protected set'' | **[[:develop:api:efl:io:buffered_stream:property:can_read|can_read]]** //**(get, set)**// | %%If %%''true''%% will notify %%[[:develop:api:efl:io:reader:method:read|Efl.Io.Reader.read]]%% can be called without blocking or failing.%% |
|  ''protected set'' | **[[:develop:api:efl:io:buffered_stream:property:can_write|can_write]]** //**(get, set)**// | %%If %%''true''%% will notify %%[[:develop:api:efl:io:writer:method:write|Efl.Io.Writer.write]]%% can be called without blocking or failing.%% |
|  | **[[:develop:api:efl:io:buffered_stream:method:clear|clear]]** | %%Clears the incoming queue. Same as reading all data.%% |
|  | **[[:develop:api:efl:io:buffered_stream:method:close|close]]** | %%Closes the Input/Output object.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:close_on_destructor|close_on_destructor]]** //**(get, set)**// | %%If true will automatically close() on object destructor.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:close_on_exec|close_on_exec]]** //**(get, set)**// | %%If true will automatically close resources on exec() calls.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:closed|closed]]** //**(get, set)**// | %%If true will notify object was closed.%% |
|  | **[[:develop:api:efl:io:buffered_stream:method:destructor|destructor]]** | %%Call the object's destructor.%% |
|  | **[[:develop:api:efl:io:buffered_stream:method:discard|discard]]** | %%Discards the given number of bytes.%% |
|  ''protected set'' | **[[:develop:api:efl:io:buffered_stream:property:eos|eos]]** //**(get, set)**// | %%If %%''true''%% will notify end of stream.%% |
|  | **[[:develop:api:efl:io:buffered_stream:method:eos_mark|eos_mark]]** | %%Marks the end-of-stream. Signals nothing else will be written.%% |
|  | **[[:develop:api:efl:io:buffered_stream:method:finalize|finalize]]** | %%Called at the end of efl_add. Should not be called, just overridden.%% |
|  | **[[:develop:api:efl:io:buffered_stream:method:flush|flush]]** | %%Forces writing all pending data to destination.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:line_delimiter|line_delimiter]]** //**(get, set)**// | %%If set incoming data will be checked for the delimiter and "line" events. The line may include the delimiter, unless it's end-of-stream in %%[[:develop:api:efl:io:buffered_stream:property:max_queue_size_input|Efl.Io.Buffered_Stream.max_queue_size_input]]%% has been reached.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:max_queue_size_input|max_queue_size_input]]** //**(get, set)**// | %%Limits how big the input queue can grow, in bytes.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:max_queue_size_output|max_queue_size_output]]** //**(get, set)**// | %%Limits how big the output queue can grow in bytes.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:pending_read|pending_read]]** //**(get)**// | %%How many bytes are pending (available) for read%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:pending_write|pending_write]]** //**(get)**// | %%How many bytes are pending write to %%[[:develop:api:efl:io:buffered_stream:property:inner_io|Efl.Io.Buffered_Stream.inner_io]]%%%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:progress|progress]]** //**(get)**// | %%How many bytes were written and read.%% |
|  | **[[:develop:api:efl:io:buffered_stream:method:read|read]]** | %%Reads data into a pre-allocated buffer.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:read_chunk_size|read_chunk_size]]** //**(get, set)**// | %%Reads chunk size property, in bytes.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:slice|slice]]** //**(get)**// | %%Gets a temporary access to input queue's internal read memory.%% |
|  | **[[:develop:api:efl:io:buffered_stream:property:timeout_inactivity|timeout_inactivity]]** //**(get, set)**// | %%Error as ETIMEDOUT if it becomes inactive for some time.%% |
|  | **[[:develop:api:efl:io:buffered_stream:method:write|write]]** | %%Writes data from a pre-populated buffer.%% |
^ [[:develop:api:efl:loop:consumer|Efl.Loop.Consumer]] ^^^
|  | **[[:develop:api:efl:loop:consumer:property:loop|loop]]** //**(get)**// | %%The loop to which this object belongs to.%% |
|  | **[[:develop:api:efl:loop:consumer:property:parent|parent]]** //**(get, set)**// | %%The parent of an object.%% |
^ [[:develop:api:efl:object|Efl.Object]] ^^^
|  | **[[:develop:api:efl:object:property:allow_parent_unref|allow_parent_unref]]** //**(get, set)**// | %%Allow an object to be deleted by unref even if it has a parent.%% |
|  | **[[:develop:api:efl:object:method:children_iterator_new|children_iterator_new]]** | %%Get an iterator on all childrens%% |
|  | **[[:develop:api:efl:object:property:comment|comment]]** //**(get, set)**// | %%A human readable comment for the object%% |
|  | **[[:develop:api:efl:object:method:composite_attach|composite_attach]]** | %%Make an object a composite object of another.%% |
|  | **[[:develop:api:efl:object:method:composite_detach|composite_detach]]** | %%Detach a composite object from another object.%% |
|  | **[[:develop:api:efl:object:method:composite_part_is|composite_part_is]]** | %%Check if an object is part of a composite object.%% |
|  | **[[:develop:api:efl:object:method:constructor|constructor]]** | %%Call the object's constructor.%% |
|  | **[[:develop:api:efl:object:method:debug_name_override|debug_name_override]]** | %%Build a read-only name for this object used for debugging.%% |
|  | **[[:develop:api:efl:object:method:del|del]]** | %%Unrefs the object and reparents it to NULL.%% |
|  | **[[:develop:api:efl:object:method:event_callback_forwarder_add|event_callback_forwarder_add]]** | %%Add an event callback forwarder for an event and an object.%% |
|  | **[[:develop:api:efl:object:method:event_callback_forwarder_del|event_callback_forwarder_del]]** | %%Remove an event callback forwarder for an event and an object.%% |
|  | **[[:develop:api:efl:object:method:event_callback_stop|event_callback_stop]]** | %%Stop the current callback call.%% |
|  | **[[:develop:api:efl:object:method:event_freeze|event_freeze]]** | %%Freeze events of object.%% |
|  | **[[:develop:api:efl:object:property:event_freeze_count|event_freeze_count]]** //**(get)**// | %%Return freeze events of object.%% |
|  ''class'' | **[[:develop:api:efl:object:method:event_global_freeze|event_global_freeze]]** | %%Freeze events of object.%% |
|  ''class'' | **[[:develop:api:efl:object:property:event_global_freeze_count|event_global_freeze_count]]** //**(get)**// | %%Return freeze events of object.%% |
|  ''class'' | **[[:develop:api:efl:object:method:event_global_thaw|event_global_thaw]]** | %%Thaw events of object.%% |
|  | **[[:develop:api:efl:object:method:event_thaw|event_thaw]]** | %%Thaw events of object.%% |
|  | **[[:develop:api:efl:object:property:finalized|finalized]]** //**(get)**// | %%True if the object is already finalized, otherwise false.%% |
|  | **[[:develop:api:efl:object:property:name|name]]** //**(get, set)**// | %%The name of the object.%% |
|  | **[[:develop:api:efl:object:method:name_find|name_find]]** | %%Find a child object with the given name and return it.%% |
|  | **[[:develop:api:efl:object:method:provider_find|provider_find]]** | %%Searches upwards in the object tree for a provider which knows the given class/interface.%% |

===== Events =====

==== Inherited ====

^ [[:develop:api:efl:io:buffered_stream|Efl.Io.Buffered_Stream]] ^^^
|  | **[[:develop:api:efl:io:buffered_stream:event:error|error]]** | %%An error has occurred and I/O has stopped%% |
|  | **[[:develop:api:efl:io:buffered_stream:event:finished|finished]]** | %%Both read and write are finished.%% |
|  | **[[:develop:api:efl:io:buffered_stream:event:line|line]]** | %%If %%[[:develop:api:efl:io:buffered_stream:property:line_delimiter|Efl.Io.Buffered_Stream.line_delimiter]]%% is set, will be emitted with current line. The memory is only valid during event callback dispatched and should not be modified. Note that the line slice may not be inside %%[[:develop:api:efl:io:buffered_stream:property:slice|Efl.Io.Buffered_Stream.slice]]%%.%% |
|  | **[[:develop:api:efl:io:buffered_stream:event:progress|progress]]** | %%Property %%[[:develop:api:efl:io:buffered_stream:property:progress|Efl.Io.Buffered_Stream.progress]]%% changed%% |
|  | **[[:develop:api:efl:io:buffered_stream:event:read_finished|read,finished]]** | %%Same as %%[[:develop:api:efl:io:reader|Efl.Io.Reader]]%% "eos", for consistency.%% |
|  | **[[:develop:api:efl:io:buffered_stream:event:slice_changed|slice,changed]]** | %%The read-slice returned by %%[[:develop:api:efl:io:buffered_stream:property:slice|Efl.Io.Buffered_Stream.slice]]%% may have changed.%% |
|  | **[[:develop:api:efl:io:buffered_stream:event:write_finished|write,finished]]** | %%%%[[:develop:api:efl:io:buffered_stream:method:eos_mark|Efl.Io.Buffered_Stream.eos_mark]]%% was called and all available data was sent to destination%% |
^ [[:develop:api:efl:io:closer|Efl.Io.Closer]] ^^^
|  | **[[:develop:api:efl:io:closer:event:closed|closed]]** | %%Notifies closed, when property is marked as true%% |
^ [[:develop:api:efl:io:reader|Efl.Io.Reader]] ^^^
|  | **[[:develop:api:efl:io:reader:event:can_read_changed|can_read,changed]]** | %%Notifies can_read property changed.%% |
|  | **[[:develop:api:efl:io:reader:event:eos|eos]]** | %%Notifies end of stream, when property is marked as true.%% |
^ [[:develop:api:efl:io:writer|Efl.Io.Writer]] ^^^
|  | **[[:develop:api:efl:io:writer:event:can_write_changed|can_write,changed]]** | %%Notifies can_write property changed.%% |
^ [[:develop:api:efl:object|Efl.Object]] ^^^
|  | **[[:develop:api:efl:object:event:callback_add|callback,add]]** | %%A callback was added.%% |
|  | **[[:develop:api:efl:object:event:callback_del|callback,del]]** | %%A callback was deleted.%% |
|  | **[[:develop:api:efl:object:event:del|del]]** | %%Object is being deleted.%% |
|  | **[[:develop:api:efl:object:event:destruct|destruct]]** | %%Object has been fully destroyed. It can not be used beyond this point. This event should only serve to clean up any dangling pointer.%% |