From 3097507197c7be13b203048df4bc0dcc776b858f Mon Sep 17 00:00:00 2001 From: Andy Williams Date: Wed, 20 Dec 2017 17:30:29 +0000 Subject: [PATCH] docs: Update ecore_con eo files for grammar and readability Author: Nate Drake --- src/lib/ecore_con/efl_net_control.eo | 64 +++++------ src/lib/ecore_con/efl_net_control_access_point.eo | 130 +++++++++++----------- src/lib/ecore_con/efl_net_control_technology.eo | 30 ++--- src/lib/ecore_con/efl_net_dialer.eo | 24 ++-- src/lib/ecore_con/efl_net_dialer_http.eo | 70 ++++++------ src/lib/ecore_con/efl_net_dialer_simple.eo | 22 ++-- src/lib/ecore_con/efl_net_dialer_websocket.eo | 36 +++--- src/lib/ecore_con/efl_net_ip_address.eo | 26 ++--- src/lib/ecore_con/efl_net_server.eo | 28 ++--- src/lib/ecore_con/efl_net_server_fd.eo | 32 +++--- src/lib/ecore_con/efl_net_server_simple.eo | 10 +- src/lib/ecore_con/efl_net_server_udp.eo | 4 +- src/lib/ecore_con/efl_net_server_udp_client.eo | 4 +- src/lib/ecore_con/efl_net_server_unix.eo | 10 +- src/lib/ecore_con/efl_net_server_windows.eo | 6 +- src/lib/ecore_con/efl_net_session.eo | 26 ++--- src/lib/ecore_con/efl_net_socket.eo | 14 +-- src/lib/ecore_con/efl_net_socket_simple.eo | 16 +-- src/lib/ecore_con/efl_net_socket_ssl.eo | 6 +- src/lib/ecore_con/efl_net_socket_udp.eo | 10 +- 20 files changed, 284 insertions(+), 284 deletions(-) diff --git a/src/lib/ecore_con/efl_net_control.eo b/src/lib/ecore_con/efl_net_control.eo index 1f98105..ad50061 100644 --- a/src/lib/ecore_con/efl_net_control.eo +++ b/src/lib/ecore_con/efl_net_control.eo @@ -5,14 +5,14 @@ import efl_net_control_technology; enum Efl.Net.Control.State { [[Provides the global network connectivity state. - For fine grained details, use @Efl.Net.Control access points and - their state property. + For more details, use @Efl.Net.Control access points and + their property state. @since 1.19 ]] - offline, [[No access point is connected]] - local, [[At least one access point was connected and the internet connectio wasn't verified]] - online, [[At least one access point was connected and the internet was verified]] + offline, [[No access point is connected.]] + local, [[At least one access point is connected and the internet connection hasn't been verified.]] + online, [[At least one access point is connected and the internet has been verified]] } enum Efl.Net.Control.Agent_Request_Input.Field { @@ -20,7 +20,7 @@ enum Efl.Net.Control.Agent_Request_Input.Field { @since 1.19 ]] - name = (1 << 0), [[Used for hidden WiFi access points. If ssid is present, this is an alternative to that.]] + name = (1 << 0), [[Used for hidden WiFi access points. If SSID is present, this is an alternative to that.]] ssid = (1 << 1), [[Used for hidden WiFi access points. If name is present, this is an alternative to that.]] username = (1 << 2), [[Identity or username requested]] passphrase = (1 << 3), [[Password or passphrase requested]] @@ -41,9 +41,9 @@ struct Efl.Net.Control.Agent_Request_Input { @since 1.19 ]] - access_point: Efl.Net.Control.Access_Point; [[The access point that triggered this request.]] + access_point: Efl.Net.Control.Access_Point; [[The access point which triggered this request.]] fields: Efl.Net.Control.Agent_Request_Input.Field; [[Bitwise OR of fields present in this request.]] - passphrase_type: string; [[Extra detail on the meaning for the passphrase field, such as wep, psk, response (IEEE802.X GTC/OTP), string...]] + passphrase_type: string; [[Extra detail for the passphrase field, such as wep, psk, response (IEEE802.X GTC/OTP), string...]] informational: list; [[Such as the previous passphrase, VPN host]] } @@ -57,7 +57,7 @@ struct Efl.Net.Control.Agent_Error { } struct Efl.Net.Control.Agent_Browser_Url { - [[Reports to agent that it should open a browser at given URL. + [[Reports to agent that it should open a browser at a given URL. @since 1.19 ]] @@ -68,50 +68,50 @@ struct Efl.Net.Control.Agent_Browser_Url { class Efl.Net.Control (Efl.Loop.Consumer) { [[Controls network connectivity. - This class and its children objects are only useful to implement - control of the network connectivity. If your application is only - interested in requesting access to the network, use the + This class and its child objects are only useful to implement + control of the network connectivity. If your application only + needs to request access to the network, use \@Efl.Net.Session instead. - The network connectivity is defined on top of technologies that + Network connectivity is defined on top of technologies that provide access points. A technology can be "ethernet", "wifi", "bluetooth" or something else. Ethernet will provide a single access point, while "wifi" will expose zero or more access points that can come and go. Users willing to use access points are expected to monitor - "access_point,add" event to know when access points were + "access_point,add" event to know when access points are added. To know when they were deleted, "access_point,del" or an @Efl.Net.Control.Access_Point "del" event. Finally "access_points,changed" is relative to additions, deletions and reordering of access point due changes in their priorities. - The backend system is responsible to remember connection details + The backend system is responsible for remembering connection details such as passphrase, last connected access point and priority. The user is NOT supposed to do that. - For ease of use, @.state tells if at least one access point is + For ease of use @.state determines if at least one access point is online (verified connectivity), local (connected but unverified) or offline. - Due safety reasons all radio transmissions may be disabled with + For safety reasons all radio transmissions may be disabled with @.radios_offline property. This is usually called "airplane - mode" in some platforms. + mode" on some platforms. Some platforms may not implement the backend for this class, in - such cases the system will report always @.state "online" + which case the system will report @.state as permanently "online" (@Efl.Net.Control.State.online) and iterators for @.access_points and @.technologies will be empty (they will be - returned but won't contain any item). + returned but won't contain any items). @since 1.19 ]] events { - access_point,add: Efl.Net.Control.Access_Point; [[The given access point was added]] + access_point,add: Efl.Net.Control.Access_Point; [[The given access point has been added]] access_point,del: Efl.Net.Control.Access_Point; [[The given access point will be deleted]] access_points,changed; [[Access points were added, deleted or reordered.]] - technology,add: Efl.Net.Control.Technology; [[The given technology was added]] + technology,add: Efl.Net.Control.Technology; [[The given technology has been added]] technology,del: Efl.Net.Control.Technology; [[The given technology will be deleted]] radios_offline,changed; [[Property @.radios_offline changed]] state,changed; [[Property @.state changed]] @@ -119,12 +119,12 @@ class Efl.Net.Control (Efl.Loop.Consumer) { agent_released; [[Notifies we're not the agent anymore]] agent_error: Efl.Net.Control.Agent_Error; [[Requires the error to be reported to the user]] agent_browser_url: Efl.Net.Control.Agent_Browser_Url; [[Requires the user to visit a web page]] - agent_request_input: Efl.Net.Control.Agent_Request_Input; [[Requires the user to enter information in order to proceed, such as hidden SSID, passphrase, etc. After the user entered information, reply by calling @.agent_reply]] + agent_request_input: Efl.Net.Control.Agent_Request_Input; [[Requires the user to enter information in order to proceed, such as hidden SSID, passphrase, etc. After the user enters the information, reply by calling @.agent_reply]] } methods { @property radios_offline { - [[If $true disable all network technologies that use radio transmission, such as bluetooth and wifi. If $false, allows radios to be used.]] + [[If $true disable all network technologies that use radio transmission, such as bluetooth and wifi. If $false, allows radio to be used.]] get { } set { } values { @@ -143,7 +143,7 @@ class Efl.Net.Control (Efl.Loop.Consumer) { - online means verified connectivity. \@note if there is no backend for this class, then state - will be always online, however @.access_points and + will always be online, however @.access_points and @.technologies will be empty iterators (valid pointers but no items in them). ]] @@ -157,7 +157,7 @@ class Efl.Net.Control (Efl.Loop.Consumer) { [[The iterator of current access points. The iterator is valid only before the function returns - to the main loop, by then, if the events + to the main loop. By then, if the events "access_point,add" or "access_point,del" are emitted, the iterator will become invalid. ]] @@ -171,7 +171,7 @@ class Efl.Net.Control (Efl.Loop.Consumer) { [[The iterator of current technologies. The iterator is valid only before the function returns - to the main loop, by then, if the events + to the main loop. By then, if the events "technology,add" or "technology,del" are emitted, the iterator will become invalid. ]] @@ -186,14 +186,14 @@ class Efl.Net.Control (Efl.Loop.Consumer) { When enabled, the local process will become the agent for user interaction, such as requesting passphrases, - asking the user to open a browser to do + asking the user to open a browser to perform web-authentication and report connection errors. - There can be a single agent in the system at a given - time, registering one will unregister the other and - special permissions may be required to become an agent. + There can be only one agent in the system at any + time: Registering one will unregister the other. + Special permissions may be required to become an agent. - An useful agent should monitor "agent_error", + A useful agent should monitor "agent_error", "agent_browser_url" and "agent_request_input" events. When input is requested, reply using @.agent_reply. diff --git a/src/lib/ecore_con/efl_net_control_access_point.eo b/src/lib/ecore_con/efl_net_control_access_point.eo index 0287b52..948325c 100644 --- a/src/lib/ecore_con/efl_net_control_access_point.eo +++ b/src/lib/ecore_con/efl_net_control_access_point.eo @@ -4,25 +4,25 @@ enum Efl.Net.Control.Access_Point.State { @since 1.19 ]] idle, [[Nothing is happening with this access point]] - association, [[The access point is trying to associate itself, this is the first state after a connection attempt]] - configuration, [[The access point is configuring itself, such as DHCP]] - local, [[The access point is connected, but the internet connection wasn't validated]] - online, [[The access point is connected and the internet connected was validated]] - disconnect, [[The access point is disconnecting]] - failure, [[A connection attempt failed, @Efl.Net.Control.Access_Point.error will provide more details]] + association, [[The access point is trying to associate itself. This is the first state after a connection attempt.]] + configuration, [[The access point is configuring itself, such as DHCP.]] + local, [[The access point is connected but the internet connection hasn't been validated.]] + online, [[The access point is connected and the internet connection has been validated.]] + disconnect, [[The access point is disconnecting.]] + failure, [[The connection attempt failed, @Efl.Net.Control.Access_Point.error will provide more details]] } enum Efl.Net.Control.Access_Point.Error { - [[The connection error reason. + [[The reason for the connection error. @since 1.19 ]] - none, [[All right, no errors]] - out_of_range, [[Wireless device is out of range]] - pin_missing, [[PIN was required and is missing]] - dhcp_failed, [[DHCP failed to provide configuration]] - connect_failed, [[Could not connect to access point]] - login_failed, [[Login or authentication information was incorrect, agent_request_input event may be emitted]] + none, [[All OK, no errors]] + out_of_range, [[Wireless device is out of range.]] + pin_missing, [[PIN was required and is missing.]] + dhcp_failed, [[DHCP failed to provide configuration.]] + connect_failed, [[Could not connect to access point.]] + login_failed, [[Login or authentication information was incorrect, agent_request_input event may be emitted.]] } enum Efl.Net.Control.Access_Point.Security { @@ -42,8 +42,8 @@ enum Efl.Net.Control.Access_Point.Ipv4_Method { @since 1.19 ]] - off, [[IPv4 is disabled]] - dhcp, [[IPv4 is configured using DHCP]] + off, [[IPv4 is disabled.]] + dhcp, [[IPv4 is configured using DHCP.]] manual, [[IPv4 is manually set using address, netmask and gateway]] unset, [[Only to be used with @Efl.Net.Control.Access_Point.configuration_ipv4]] } @@ -53,25 +53,25 @@ enum Efl.Net.Control.Access_Point.Ipv6_Method { @since 1.19 ]] - off, [[IPv6 is disabled]] - fixed, [[IPv6 is fixed by operator and cannot be changed]] - manual, [[IPv6 is manually set using address, netmask and gateway]] - auto_privacy_none, [[IPv6 is set using dhcp or using a tunnel6to4, no privacy extensions should be used]] - auto_privacy_public, [[IPv6 is set using dhcp or using a tunnel6to4, privacy extensions are used and the system prefers a public IP address over temporary addresses]] - auto_privacy_temporary, [[IPv6 is set using dhcp or using a tunnel6to4, privacy extensions are used and the system prefers a temporary IP address over public addresses]] - tunnel6to4, [[IPv6 was configured using a 6-to-4 tunnel. This cannot be set by the user, which is expected to set "auto" instead]] + off, [[IPv6 is disabled.]] + fixed, [[IPv6 is fixed by operator and cannot be changed.]] + manual, [[IPv6 is manually set using address, netmask and gateway.]] + auto_privacy_none, [[IPv6 is set using dhcp or using a tunnel6to4. No privacy extensions should be used.]] + auto_privacy_public, [[IPv6 is set using dhcp or using a tunnel6to4, privacy extensions are used and the system prefers a public IP address over temporary addresses.]] + auto_privacy_temporary, [[IPv6 is set using dhcp or using a tunnel6to4, privacy extensions are used and the system prefers a temporary IP address over public addresses.]] + tunnel6to4, [[IPv6 was configured using a 6-to-4 tunnel. This cannot be set by the user, which is set to "auto" instead]] unset, [[Only to be used with @Efl.Net.Control.Access_Point.configuration_ipv6]] } enum Efl.Net.Control.Access_Point.Proxy_Method { - [[The method used to configure Proxy. + [[The method used to configure Proxies. @since 1.19 ]] - off, [[Direct connection to the internet, no proxy to be used]] - auto, [[Proxy is autoconfigured using Proxy-Auto-Configuration (PAC) using given URL]] - manual, [[Proxy is configured manually using servers and excludes]] - unset, [[Only to be used with @Efl.Net.Control.Access_Point.configuration_proxy]] + off, [[Direct connection to the internet, no proxy used.]] + auto, [[Proxy is autoconfigured using Proxy-Auto-Configuration (PAC) using given URL.]] + manual, [[Proxy is configured manually using servers and excludes.]] + unset, [[Only to be used with @Efl.Net.Control.Access_Point.configuration_proxy.]] } class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @@ -80,8 +80,8 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { The @Efl.Net.Control is composed of multiple technologies, each create access points to allow configuration and connection. - An application willing to just get a network connection should - prefer to use the \@Efl.Net.Session instead. + An application requiring only a network connection can just + use a \@Efl.Net.Session instead. @since 1.19 ]] @@ -114,11 +114,11 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { disconnect { [[Disconnects from this access point. - When disconnected a previously connected access point it + When disconnected previously connected access points won't be forgotten. The configuration and other details - such as priority and passphrase will be available for a - future re-connection with call to @.connect. If it is - desired to disconnect and forget all access point + such as priority and passphrase will be available for + future re-connection with a call to @.connect. If you + need to disconnect and forget all access point information, use @.forget instead. ]] } @@ -127,15 +127,15 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { [[Disconnects and forgets about this access point. Successful @.connect will always remember the access - point for future re-connections. This method reverts - that by disconnecting and forgetting about the access - point and its configuration, which will set the + point for future re-connections. This method overrides + this by disconnecting and forgetting the access + point and its configuration, which will set @.remembered to $false. ]] } @property state { - [[The current state of this access point. + [[The current state of the access point. Whenever the state changes, "changed" will be emitted. ]] @@ -170,16 +170,16 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { This property is dynamic and reflects the index of the access point in the current access points list. As access points may come and go, the value may change at - any time and notified with "changed" event. + any time and send notifications via the "changed" event. If set, then it will reorder priorities, moving all other services at equal or higher priority up. To move as the first (most priority), then use 0. To move as the last priority, use UINT32_MAX or the last known priority + 1. - \@note Only remembered access points may be reordered + \@note Only stored access points may be reordered among themselves. Those that are not remembered will - always come last in random order defined by the backend. + always come last in a random order defined by the backend. ]] get { } set { } @@ -259,9 +259,9 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property name_servers { [[DNS (Domain Name Servers) in use for this access point. - These are the actual values in use, configure them using - @.configuration_name_servers, which may generate change - to this property, being notified with the "changed" + These are the actual values used. Configure them using + @.configuration_name_servers. This may generate changes + to this property, triggering the "changed" event. ]] get { } @@ -273,9 +273,9 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property time_servers { [[NTP (Time Server) in use for this access point. - These are the actual values in use, configure them using - @.configuration_time_servers, which may generate change - to this property, being notified with the "changed" + These are the actual values used. Configure them using + @.configuration_name_servers. This may generate changes + to this property, triggering the "changed" event. ]] get { } @@ -287,9 +287,9 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property domains { [[Searches domains in use for this access point. - These are the actual values in use, configure them using - @.configuration_domains, which may generate change - to this property, being notified with the "changed" + These are the actual values used. Configure them using + @.configuration_name_servers. This may generate changes + to this property, triggering the "changed" event. ]] get { } @@ -301,9 +301,9 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property ipv4 { [[IPv4 in use for this access point. - These are the actual values in use, configure them using - @.configuration_ipv4, which may generate change - to this property, being notified with the "changed" + These are the actual values used. Configure them using + @.configuration_name_servers. This may generate changes + to this property, triggering the "changed" event. ]] get { } @@ -318,9 +318,9 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property ipv6 { [[IPv6 in use for this access point. - These are the actual values in use, configure them using - @.configuration_ipv6, which may generate change - to this property, being notified with the "changed" + These are the actual values used. Configure them using + @.configuration_name_servers. This may generate changes + to this property, triggering the "changed" event. ]] get { } @@ -336,9 +336,9 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property proxy { [[Proxy in use for this access point. - These are the actual values in use, configure them using - @.configuration_proxy, which may generate change - to this property, being notified with the "changed" + These are the actual values used. Configure them using + @.configuration_name_servers. This may generate changes + to this property, triggering the "changed" event. ]] get { } @@ -353,7 +353,7 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property configuration_name_servers { [[DNS (Domain Name Servers) configured by user for this access point. - These are the user configured values, that will be + These are user configured values, which will be applied by the backend system and in turn may result in "changed" event to notify of @.name_servers property with the actual value in use, which may differ from @@ -369,9 +369,9 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property configuration_time_servers { [[NTP (Time Server) configured by user for this access point. - These are the user configured values, that will be + These are user configured values, which will be applied by the backend system and in turn may result in - "changed" event to notify of @.time_servers property + "changed" event to notify of @.name_servers property with the actual value in use, which may differ from this. ]] @@ -385,7 +385,7 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property configuration_domains { [[Searches domains configured by user for this access point. - These are the user configured values, that will be + These are user configured values, which will be applied by the backend system and in turn may result in "changed" event to notify of @.domains property with the actual value in use, which may differ from @@ -401,7 +401,7 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property configuration_ipv4 { [[IPv4 configured by user for this access point. - These are the user configured values, that will be + These are user configured values, which will be applied by the backend system and in turn may result in "changed" event to notify of @.ipv4 property with the actual value in use, which may differ from @@ -420,7 +420,7 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property configuration_ipv6 { [[IPv6 configured by user for this access point. - These are the user configured values, that will be + These are user configured values, which will be applied by the backend system and in turn may result in "changed" event to notify of @.ipv6 property with the actual value in use, which may differ from @@ -440,7 +440,7 @@ class Efl.Net.Control.Access_Point (Efl.Loop.Consumer) { @property configuration_proxy { [[Proxy configured by user for this access point. - These are the user configured values, that will be + These are user configured values, which will be applied by the backend system and in turn may result in "changed" event to notify of @.proxy property with the actual value in use, which may differ from diff --git a/src/lib/ecore_con/efl_net_control_technology.eo b/src/lib/ecore_con/efl_net_control_technology.eo index 2dd1784..f65d702 100644 --- a/src/lib/ecore_con/efl_net_control_technology.eo +++ b/src/lib/ecore_con/efl_net_control_technology.eo @@ -16,13 +16,13 @@ enum Efl.Net.Control.Technology.Type { } class Efl.Net.Control.Technology (Efl.Loop.Consumer) { - [[A technology that enables network access points to be controlled. + [[A technology that allows control of network access points. The @Efl.Net.Control is composed of multiple technologies, each can be disabled/enabled with @.powered property. - When powered, the technology will dynamically add and delete - access points to be available in + When powered, the technology will dynamically create and remove + access points in @Efl.Net.Control.access_points. @since 1.19 @@ -44,16 +44,16 @@ class Efl.Net.Control.Technology (Efl.Loop.Consumer) { @property tethering { [[Tethering allows the default access point to be bridged to all clients connected through the technology. - A common case is to use the device as a router, such as - a phone doing tethering allows a laptop to connect to 4G + A common use case is to deploy the device as a router, such as + a tethered phone allowing a laptop to connect to a 4G network. ]] get { } set { } values { - enabled: bool; [[Whenever to enable or disable tethering for this technology]] - identifier: string @optional; [[The name to identify this tethering, in WiFi it will translate to SSID.]] - passphrase: string @optional; [[The passphrase for this tethering access, in WiFi it will translate to WPA passphrase.]] + enabled: bool; [[When to enable or disable tethering for this technology.]] + identifier: string @optional; [[The name to identify the tethering. For WiFi this will translate to an SSID.]] + passphrase: string @optional; [[The passphrase for tethering access. For WiFi this will translate to WPA passphrase.]] } } @@ -87,14 +87,14 @@ class Efl.Net.Control.Technology (Efl.Loop.Consumer) { The scan will happen asynchronously in the background, with the results being delivered by events in the technology, @Efl.Net.Control or @Efl.Net.Control.Access_Point - associated with the technology. For example, scan on - WiFi will add and delete access points. + associated with the technology. For example, a scan on + WiFi will add and remove access points. - It is worth to mention that explicit scans should be - avoided. Rare cases are when user requested them, like - entering a configuration dialog which demands fresh - state. Otherwise prefer to let the system passively do - scans in a timely manner. + Try to avoid explicit scans. + Rare exceptions to this rule include when the user requests them, + such as entering a configuration dialog which demands a fresh + state. Otherwise allow the system to perform + passive scans in a timely manner. ]] return: ptr(Eina.Future) @owned; [[Future return for finished background scan]] } diff --git a/src/lib/ecore_con/efl_net_dialer.eo b/src/lib/ecore_con/efl_net_dialer.eo index 8cde0c9..08cf843 100644 --- a/src/lib/ecore_con/efl_net_dialer.eo +++ b/src/lib/ecore_con/efl_net_dialer.eo @@ -5,13 +5,13 @@ var Efl.Net.Dialer.Error.PROXY_AUTHENTICATION_FAILED: Eina.Error; [[The dialer f interface Efl.Net.Dialer (Efl.Net.Socket) { [[Creates a client socket to reach a remote peer. - The connection process starts when @.dial is executed, this - allows implementations to request more complex setup that would - require a live object handle that is not possible during + The connection process starts when @.dial is executed. This + allows implementations to request more complex setups + requiring a live object handle, which is not possible during construction. The socket should be considered connected and ready to use only - when "connected" event is dispatched, by then + when "connected" event is dispatched. By then @Efl.Io.Reader.can_read and @Efl.Io.Writer.can_write should change accordingly. @@ -24,10 +24,10 @@ interface Efl.Net.Dialer (Efl.Net.Socket) { dial { [[Dials to the remote peer. - This method starts the connection process, resolving - address and then proceeding to the actual connection. + This method starts the connection process, resolves the + address and then proceeds to the actual connection. - Once the connection is fully setup, "connected" event is + Once the connection is fully setup "connected" event is dispatched. ]] params { @@ -39,7 +39,7 @@ interface Efl.Net.Dialer (Efl.Net.Socket) { @property address_dial { [[Returns the address given to @.dial. - If the resolved address is desired, then listen to + If the resolved address is required, listen to "resolved" event and use the @Efl.Net.Socket.address_remote property. ]] @@ -53,7 +53,7 @@ interface Efl.Net.Dialer (Efl.Net.Socket) { @property connected { [[Returns whenever the socket is connected or not. - Whenever this property becomes true, "connected" event + Whenever this property becomes true the "connected" event should be dispatched. ]] get { } @@ -70,8 +70,8 @@ interface Efl.Net.Dialer (Efl.Net.Socket) { - protocol://username:password\@proxyserver:port - Where protocol is defined per class, such as a TCP or - UDP dialer will use 'socks4', 'socks4a', 'socks5' or + Where protocol is defined by class, such as a TCP or + UDP, dialer will use 'socks4', 'socks4a', 'socks5' or 'socks5h'; while http and websocket will want those or 'http'. @@ -115,7 +115,7 @@ interface Efl.Net.Dialer (Efl.Net.Socket) { @Efl.Net.Socket.address_remote. This is emitted before "connected" and may - be emitted from @Efl.Object.finalize, thus + be emitted from @Efl.Object.finalize. As such be sure to connect the callbacks during the object construction. diff --git a/src/lib/ecore_con/efl_net_dialer_http.eo b/src/lib/ecore_con/efl_net_dialer_http.eo index 3c2e524..4d18fe5 100644 --- a/src/lib/ecore_con/efl_net_dialer_http.eo +++ b/src/lib/ecore_con/efl_net_dialer_http.eo @@ -14,17 +14,17 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { available as @Efl.Net.Socket.address_remote. The @Efl.Net.Socket.address_local is an IP:PORT pair. - The dialer can do bi-directional information exchange. It can - also do a PUT and upload a file, or GET and download one. Anoter - case is to do a POST with some form values, including a file, - and retrieve its headers and response body. To make usage more - streamlined, choose your primary interest with @.primary_mode + The dialer can perform bi-directional information exchanges. It can + also do a PUT and upload a file, or GET and download one. It can + also do a POST with some form values, including a file, + and retrieve its headers and body response. To make usage more + streamlined, choose your area of interest with @.primary_mode then get some properties such as @Efl.Io.Sizer.size to report or - use what matters to your use case. + use the information you need. If @.allow_redirects is $true, multiple "connected" and "resolved" signals will be dispatched, one for each - connection. Then @.response_status and @.response_headers_get + connection. In this case @.response_status and @.response_headers_get will keep changing. Using @.response_headers_all_get one can see the whole history of headers and connections. @@ -35,7 +35,7 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { used. On UNIX that's the environment variable $http_proxy (or '$all_proxy') is used if the given address doesn't match $no_proxy patterns. To disable proxy use an empty string. If - provided proxy must be one of the protocols: + provided, the proxy must use one of the following protocols: - http://username:password\@proxyserver:port - http://username\@proxyserver:port @@ -88,7 +88,7 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { @Efl.Io.Sizer.size.get will report the "Content-Length" provided by the server, if any. - If is worth to mention that one can provide and + You can also provide and retrieve these values using @.request_headers_get (to send) and @.response_headers_get (what was received), as well as using the specific properties @@ -148,7 +148,7 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { values { username: string; [[HTTP authentication username]] password: string; [[HTTP authentication password]] - method: Efl.Net.Http.Authentication_Method @optional; [[Authentication method to use, defaults to @Efl.Net.Http.Authentication_Method.basic]] + method: Efl.Net.Http.Authentication_Method @optional; [[Authentication method to use. Defaults to @Efl.Net.Http.Authentication_Method.basic]] restricted: bool @optional; [[Restrict method]] } } @@ -228,12 +228,12 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { @property response_status { [[The HTTP response status of this request. - It will be 0 if not connected, otherwise will be what is - returned by the server, such as. + This will be 0 if not connected, otherwise it'll be whatever is + returned by the server. See https://en.wikipedia.org/wiki/List_of_HTTP_status_codes - This will be usable after "connected" event is dispatched. + This will be usable after the "connected" event is dispatched. ]] get { } values { @@ -244,13 +244,13 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { response_headers_get { [[Returns an iterator to the key-value pairs for the last response headers. - Since multiple requests can happen if @.allow_redirects + Since multiple requests can occur if @.allow_redirects is true, then all headers will be accumulated. This method returns only the headers for the last request. - To know all the headers, check @.response_headers_all_get. + To list all the headers, check @.response_headers_all_get. - This will be usable after "headers,done" event is dispatched. + This will be usable after the "headers,done" event is dispatched. ]] return: iterator @owned @warn_unused; [[Iterator for response headers]] } @@ -258,10 +258,10 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { response_headers_all_get { [[Returns an iterator to the key-value pairs for all response headers. - Since multiple requests can happen if @.allow_redirects + Since multiple requests can occur if @.allow_redirects is true, then all headers will be accumulated. To know - when new request is started, check for headers with keys - being NULL, the value will be the "HTTP/VERSION RESPONSE" + when a new request's been started, check for headers with keys + being NULL. The value will be the "HTTP/VERSION RESPONSE" string received from the host, such as: - key=NULL, value="HTTP/1.1 302 Found" @@ -269,23 +269,23 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { - key=NULL, value="HTTP/1.1 200 Ok" - key="Content-Type", value="text/html" - Which mean the original request had a redirect to + This means the original request had a redirect to http://someredirect.com. - To receive an iterator to just the last request, use + To receive an iterator to only the last request, use @.response_headers_get - This will be usable after "headers,done" event is dispatched. + This will be usable after the "headers,done" event is dispatched. ]] return: iterator @owned @warn_unused; [[Iterator for all response headers]] } response_headers_clear { - [[Saves some memory by disposing the received headers]] + [[Saves memory by disposing of the received headers]] } @property progress_download { - [[How many bytes were downloaded and how much was expected.]] + [[How many bytes were downloaded and how many were expected.]] get { } values { downloaded: uint64 @optional; [[Downloaded bytes so far]] @@ -294,7 +294,7 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { } @property progress_upload { - [[How many bytes were uploaded and how much was expected.]] + [[How many bytes were uploaded and how many were expected.]] get { } values { uploaded: uint64 @optional; [[Uploaded bytes so far]] @@ -303,29 +303,29 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { } @property cookie_jar { - [[This property sets the filename where to read and write cookies. + [[This property sets the filename to read and write cookies. - By setting a file to load and persist cookies to, the + By setting a file to load and store cookies, the internal cookie system will be activated, automatically handling HTTP headers such as 'Set-cookie:' and sending - the appropriate cookies for a server. + the appropriate cookies for the server. If a new, empty session is to be used, start with an empty or non-existent file such as created with - mkstemp() or tmpfile(). An alternative is to use an - empty string ("") to keep it in memory. + mkstemp() or tmpfile(). Alternatively use an + empty string ("") to store it in memory. - If it is desired to start from a pre-existent cookie jar - but do not want to modify that, first copy that file and + If you want to start from a pre-existing cookie jar + but do not want to modify it, first copy that file and then pass the new, temporary file. - Likewise, if it's desired to fill some cookies to the + Likewise, if you want to add cookies to the system, create a cookie jar and pass its path to this property. \@note that whenever this property is set, even if to the same value, it will flush all cookies to the previously - set file, then erase all known cookies, then use the new + set file, then erase all known cookies. It will then use the new file (if any). ]] get { } @@ -342,7 +342,7 @@ class Efl.Net.Dialer.Http (Efl.Loop.Consumer, Efl.Net.Dialer, Efl.Io.Sizer) { ]] values { peer: bool; [[If $true, SSL certificate will be verified. If $false, untrusted certificates (including self signed) will be accepted.]] - hostname: bool; [[If $true, in addition to SSL certificate validation, the server name will be matched to certificate DNS entries]] + hostname: bool; [[If $true, in addition to SSL certificate validation the server name will be matched to certificate DNS entries]] } } diff --git a/src/lib/ecore_con/efl_net_dialer_simple.eo b/src/lib/ecore_con/efl_net_dialer_simple.eo index b26cfd1..ceeca6c 100644 --- a/src/lib/ecore_con/efl_net_dialer_simple.eo +++ b/src/lib/ecore_con/efl_net_dialer_simple.eo @@ -1,17 +1,17 @@ class Efl.Net.Dialer.Simple (Efl.Net.Socket.Simple, Efl.Net.Dialer) { [[Connects to a remote server offering an easy to use, buffered I/O. - The simple dialer is based on @Efl.Net.Socket.Simple, that - encapsulates an actual @Efl.Net.Socket, and uses it with an - @Efl.Io.Buffered_Stream, which creates an input @Efl.Io.Queue, - an output @Efl.Io.Queue and these are linked using a receiver + The simple dialer is based on @Efl.Net.Socket.Simple, which + encapsulates an actual @Efl.Net.Socket and uses it with an + @Efl.Io.Buffered_Stream. This creates an input @Efl.Io.Queue, + an output @Efl.Io.Queue. Both of these are linked using a receiver and a sender @Efl.Io.Copier. - The idea is that unlike traditional @Efl.Net.Socket that will - attempt to write directly to socket and thus may take less data + The idea is that unlike the traditional @Efl.Net.Socket which + attempts to write directly to the 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 it - @Efl.Io.Writer.can_write. That makes its operation much simpler + buffer, feeding it to the actual socket when + @Efl.Io.Writer.can_write occurs. This makes its operation much simpler as @Efl.Io.Writer.write will always take the full data -- allows "write and forget", if unlimited (see @Efl.Io.Buffered_Stream.max_queue_size_output). @@ -24,15 +24,15 @@ class Efl.Net.Dialer.Simple (Efl.Net.Socket.Simple, Efl.Net.Dialer) { @Efl.Io.Buffered_Stream.discard or @Efl.Io.Buffered_Stream.clear. - Then when waiting for a complete message, just peek at its - contents, if not complete do nothing, if complete then either + When waiting for a complete message, you can then just peek at its + contents. If it's incomplete do nothing, if complete then either @Efl.Io.Reader.read to get a copy or manipulate a read-only reference from @Efl.Io.Buffered_Stream.slice and then @Efl.Io.Buffered_Stream.discard The actual dialer is created using the class given as the constructor property @.inner_class and can be retrieved with - @Efl.Io.Buffered_Stream.inner_io, which should be used with + @Efl.Io.Buffered_Stream.inner_io. This should be used with care, like extra configuration before @Efl.Net.Dialer.dial is called. diff --git a/src/lib/ecore_con/efl_net_dialer_websocket.eo b/src/lib/ecore_con/efl_net_dialer_websocket.eo index 27f7974..d927474 100644 --- a/src/lib/ecore_con/efl_net_dialer_websocket.eo +++ b/src/lib/ecore_con/efl_net_dialer_websocket.eo @@ -54,15 +54,15 @@ class Efl.Net.Dialer.Websocket (Efl.Loop.Consumer, Efl.Net.Dialer) { a message-based protocol over HTTP, this allows it to leverage on authentication, cookies, proxies and SSL/TLS. - It's worth to note that although it uses the HTTP dialer, it's + Although it uses the HTTP dialer, it's not a subclass and thus not all HTTP features are exposed as the WebSocket has strict requirements that must be respected. If the proxy is NULL (default), then the system proxy will be used. On UNIX that's the environment variable $http_proxy (or '$all_proxy') is used if the given address doesn't match - $no_proxy patterns. To disable proxy use an empty string. If - provided proxy must be one of the protocols: + $no_proxy patterns. To disable the proxy use an empty string. If + provided, the proxy must be one of the following protocols: - http://username:password\@proxyserver:port - http://username\@proxyserver:port @@ -82,7 +82,7 @@ class Efl.Net.Dialer.Websocket (Efl.Loop.Consumer, Efl.Net.Dialer) { ping { [[Sends a PING (opcode=0x9) to the server. - The server should reply with a PONG, that will be + The server should reply with a PONG, which will be emitted as "pong" event. ]] @@ -94,10 +94,10 @@ class Efl.Net.Dialer.Websocket (Efl.Loop.Consumer, Efl.Net.Dialer) { text_send { [[Sends an UTF-8 TEXT (opcode=0x1) to the server. - The text goes in a message will be delivered as a single + The message text will be delivered as a single entity to the remote peer. - The text is copied into a local buffer, no references + The text is copied into a local buffer. No references are kept after this method returns. ]] params { @@ -108,7 +108,7 @@ class Efl.Net.Dialer.Websocket (Efl.Loop.Consumer, Efl.Net.Dialer) { binary_send { [[Sends a binary blob (opcode=0x2) to the server. - The slice describing the blob goes in a message will be + The slice describing the blob goes in a message which will be delivered as a single entity to the remote peer. The memory is copied into a local buffer, no references @@ -123,16 +123,16 @@ class Efl.Net.Dialer.Websocket (Efl.Loop.Consumer, Efl.Net.Dialer) { [[Requests (opcode=0x8) the server to terminate the connection. Unlike @Efl.Io.Closer.close, this won't abruptly close - the connection, rather will queue a message requesting + the connection, rather it'll queue a message requesting the server to gracefully close it. After this method is called you should consider the - object in "closing" state, no more messages can be sent + object in "closing" state. No more messages can be sent (@.text_send, @.binary_send and @.ping will fail). The object will be automatically closed with - @Efl.Io.Closer.close once the serve replies with his own - close message, that will be reported as "closed,reason". + @Efl.Io.Closer.close once the server replies with his own + close message, which will be reported as "closed,reason". ]] params { reason: Efl.Net.Dialer.Websocket.Close_Reason; [[Reason for closing]] @@ -215,7 +215,7 @@ class Efl.Net.Dialer.Websocket (Efl.Loop.Consumer, Efl.Net.Dialer) { values { username: string; [[HTTP authentication username]] password: string; [[HTTP authentication password]] - method: Efl.Net.Http.Authentication_Method @optional; [[Authentication method to use, defaults to @Efl.Net.Http.Authentication_Method.basic]] + method: Efl.Net.Http.Authentication_Method @optional; [[The authentication method to use. Defaults to @Efl.Net.Http.Authentication_Method.basic]] restricted: bool @optional; [[Restrict method]] } } @@ -274,21 +274,21 @@ class Efl.Net.Dialer.Websocket (Efl.Loop.Consumer, Efl.Net.Dialer) { @property cookie_jar { [[This property sets the filename where to read and write cookies. - By setting a file to load and persist cookies to, the + By setting a file to load and store cookies, the internal cookie system will be activated, automatically handling HTTP headers such as 'Set-cookie:' and sending the appropriate cookies for a server. If a new, empty session is to be used, start with an - empty or non-existent file such as created with - mkstemp() or tmpfile(). An alternative is to use an + empty or non-existent file such as one created with + mkstemp() or tmpfile(). Alternatively use an empty string ("") to keep it in memory. - If it is desired to start from a pre-existent cookie jar - but do not want to modify that, first copy that file and + If you want to start from a pre-existent cookie jar + but do not want to modify it, first copy that file and then pass the new, temporary file. - Likewise, if it's desired to fill some cookies to the + Likewise, if you want to store some cookies in the system, create a cookie jar and pass its path to this property. diff --git a/src/lib/ecore_con/efl_net_ip_address.eo b/src/lib/ecore_con/efl_net_ip_address.eo index b3fc564..e715a0c 100644 --- a/src/lib/ecore_con/efl_net_ip_address.eo +++ b/src/lib/ecore_con/efl_net_ip_address.eo @@ -9,14 +9,14 @@ struct Efl.Net.Ip_Address.Resolve_Results { ]] request_address: string; [[The 'address' argument given to Efl.Net.Ip_Address.resolve]] canonical_name: string; [[The canonical name, if it was requested in flags]] - results: array; [[The resolved objects. Do not modify this array, but you can keep reference to elements using efl_ref() and efl_unref()]] + results: array; [[The resolved objects. Do not modify this array but you can keep reference to elements using efl_ref() and efl_unref()]] } class Efl.Net.Ip_Address (Efl.Object) { [[An Internet Protocol (IP) Address. This class is a set of helpers to translate to and from address - strings used in Efl.Net. For IP they take the formats: + strings used in Efl.Net. For IP they take the following formats: - IPv4 complete: 127.0.0.1:1234 - IPv4 no port: 127.0.0.1 @@ -24,9 +24,9 @@ class Efl.Net.Ip_Address (Efl.Object) { - IPv6 no port: [::1] - IPv6 no braces (implies no port): ::1 - However in other libraries one may use the address numbers or - even a 'struct sockaddr' handle and translating by yourself may - be too much work. To convert to a string, just create an + However in other libraries you can use the address numbers or + even a 'struct sockaddr' handle. Translating by yourself may + be too much work. To convert to a string just create an instance with @.create or @.create_sockaddr and then query @.string. To convert from numeric string to sockaddr, create an instance with @.parse and then query @.sockaddr. @@ -58,9 +58,9 @@ class Efl.Net.Ip_Address (Efl.Object) { create_sockaddr @class { [[Creates an object given sockaddr - This is a convenience to create an object in a single call. - To create based on native port and address bytes, - use @.create, to create from string use @.parse. + This is a convenient way to create an object in a single call. + To create based on native port and address bytes + use @.create. To create from a string use @.parse. ]] params { sockaddr: const(void_ptr) @nonull; [[The pointer to struct sockaddr-compatible handle as per .]] @@ -108,7 +108,7 @@ class Efl.Net.Ip_Address (Efl.Object) { and port. ]] params { - address: string @nonull; [[The address such as enlightenment.org:http or enlightenment.org (port=0)]] + address: string @nonull; [[The address, such as enlightenment.org:http or enlightenment.org (port=0)]] family: int @optional; [[Preferred family. AF_UNSPEC or 0 for both, otherwise one of AF_INET or AF_INET6]] flags: int @optional; [[Flags to use with getaddrinfo(). If 0, default flags are used (AI_V4MAPPED | AI_ADDRCONFIG, if these exist in your system).]] } @@ -134,7 +134,7 @@ class Efl.Net.Ip_Address (Efl.Object) { @property family { [[The address family, one of AF_INET6 or AF_INET. - May only be set once, afterwards the object is not changing. + May only be set once. Afterwards the object does not change. ]] values { family: int; [[AF_INET or AF_INET6]] @@ -144,7 +144,7 @@ class Efl.Net.Ip_Address (Efl.Object) { @property port { [[The address port in Host/Native endianess. - May only be set once, afterwards the object is not changing. + May only be set once. Afterwards the object does not change. Must be set after @.family. ]] @@ -156,7 +156,7 @@ class Efl.Net.Ip_Address (Efl.Object) { @property address { [[The bytes representing the address. - May only be set once, afterwards the object is not changing. + May only be set once. Afterwards the object does not change. Must be set after @.family. ]] @@ -168,7 +168,7 @@ class Efl.Net.Ip_Address (Efl.Object) { @property sockaddr { [[The -compatible 'struct sockaddr'. - May only be set once, afterwards the object is not changing. + May only be set once. Afterwards the object does not change. ]] values { sockaddr: const(void_ptr) @nonull; [[Sockaddr struct. As usual with struct sockaddr, the first field, struct sockaddr::sa_family, defines the rest of the structure and how the whole structure must be interpreted. If AF_INET is struct sockaddr_in, AF_INET6 is struct sockaddr_in6.]] diff --git a/src/lib/ecore_con/efl_net_server.eo b/src/lib/ecore_con/efl_net_server.eo index ab26e22..f6d29c4 100644 --- a/src/lib/ecore_con/efl_net_server.eo +++ b/src/lib/ecore_con/efl_net_server.eo @@ -1,20 +1,20 @@ interface Efl.Net.Server { [[The basic server interface. - It will start serving and accepting clients once @.serve is + This will start serving and accepting clients once @.serve is called and the "serving" event is dispatched. - When new clients are accepted, then "client,add" event is + When new clients are accepted the "client,add" event is dispatched with a child object implementing @Efl.Net.Socket interface. These implement the standard @Efl.Io.Reader, - @Efl.Io.Writer and @Efl.Io.Closer interfaces, thus can be used + @Efl.Io.Writer and @Efl.Io.Closer interfaces, so can be used with utilities such as @Efl.Io.Copier. @since 1.19 ]] events { - client,add @hot: Efl.Net.Socket; [[A new client socket was created. + client,add @hot: Efl.Net.Socket; [[A new client socket has been created. The socket will have the server as parent and can be @@ -26,7 +26,7 @@ interface Efl.Net.Server { excess, see @.clients_limit. ]] - error: Eina.Error; [[Some error happened and the server needs + error: Eina.Error; [[An error has occurred and the server needs to be stopped. ]] serving; [[Notifies the server is ready to accept clients. @@ -37,11 +37,11 @@ interface Efl.Net.Server { serve { [[Starts serving requests. - This method starts the server, resolving address and - then proceeding to the actual listen(2)/bind(2) + This method starts the server, resolves addresses and + then proceeds to the actual listen(2)/bind(2) equivalent.. - Once the connection is fully setup, "serving" event is + Once the connection is fully set up the "serving" event is dispatched. ]] params { @@ -51,14 +51,14 @@ interface Efl.Net.Server { } @property address { - [[The address the server is bound to. + [[The address to which the server is bound. - The actual value depends on the type of server, like an + The actual value depends on the type of server, such as an IPv4 (ip:port) or IPv6 ([ip]:port) formatted for a TCP/UDP server, the path if an Unix Local... - It's always resolved, then if operations are working - with domain names or URL, this is the values the kernel + It's always resolved. If operations are working + with domain names or URLs, these are the values the kernel reports. It's similar to getsockname() in behavior. ]] get { } @@ -69,7 +69,7 @@ interface Efl.Net.Server { } @property clients_count { - [[Number of concurrent clients accepted by this server.]] + [[Number of concurrent clients accepted by the server.]] get { } set @protected { } values { @@ -78,7 +78,7 @@ interface Efl.Net.Server { } @property clients_limit { - [[Number of maximum concurrent clients allowed by this server. + [[Number of maximum concurrent clients allowed by the server. If reject_excess is set to true, then the connection will be accepted and immediately closed. diff --git a/src/lib/ecore_con/efl_net_server_fd.eo b/src/lib/ecore_con/efl_net_server_fd.eo index 4cc6676..db558ec 100644 --- a/src/lib/ecore_con/efl_net_server_fd.eo +++ b/src/lib/ecore_con/efl_net_server_fd.eo @@ -6,48 +6,48 @@ class Efl.Net.Server.Fd (Efl.Loop.Fd, Efl.Net.Server) { methods { socket_activate { - [[If this method is called use an already activated socket. + [[If this method is called, use an already activated socket. This method allows a server to use an existing socket - received from systemd or similar system. + received from systemd or any similar system. It will replace @Efl.Net.Server.serve, thus if this is - used, that method will return EALREADY. + used, this method will return EALREADY. \@note The parameter 'address' given to this function is - only used to validate the next socket available, it + only used to validate the next socket available. It doesn't search for a socket with the given address. Thus - the socket to be used is the next unused and orders - matter is using multiple servers! + the socket to be used is the next unused one : order + matters if using multiple servers! \@note subclasses must validate the socket and return EINVAL prior to call the base class with Efl.Object.super. They must also emit "serving" when - ready, for instance stream protocols may need to check - for listening and if not try to listen. Usually they + ready. For instance stream protocols may need to check + for listening and if not, try to listen. Usually they will also query getsockname() and set @Efl.Net.Server.address. Errors: - - EALREADY: already have a socket, either from + - EALREADY: There already is a socket, either from previous @.socket_activate or @Efl.Net.Server.serve. Usually represents a programming error. - - ENOENT: no sockets received from process manager + - ENOENT: No sockets received from process manager (ie: systemd). Usually this is not a fatal error, just proceed by calling @Efl.Net.Server.serve - EINVAL: the socket received is not of the correct family, type or protocol. Usually this means a - configuration mismatch with the order of server + configuration mismatch between the order of server creation and calls to socket_activate. The systemd.socket entries must match the order in your application. ]] params { - address: string; [[The address to validate the next available socket. It doesn't serve as search, only as validation!]] + address: string; [[The address to validate the next available socket. It cannot be used to search, only for validation.]] } return: Eina.Error; [[$0 on success, ENOENT if no socket is available or EALREADY if already have a socket]] } @@ -71,8 +71,8 @@ class Efl.Net.Server.Fd (Efl.Loop.Fd, Efl.Net.Server) { @property close_on_exec { [[Controls Close-on-Exec() using FD_CLOEXEC. - Children socket will inherit the server's setting by - default. One can change the behavior using each instance + Child sockets inherit the server's settings by + default. You can change the behavior using each instance @Efl.Io.Closer.close_on_exec.set. Defaults to $true. ]] get { } @@ -125,7 +125,7 @@ class Efl.Net.Server.Fd (Efl.Loop.Fd, Efl.Net.Server) { [[Accepts a new client, should emit "client,add". Remember to create the client object with a callback to - EFL_IO_CLOSER_EVENT_CLOSED during the construction and + EFL_IO_CLOSER_EVENT_CLOSED during the construction, decrease @Efl.Net.Server.clients_count as well as unref the client and remove yourself as parent. @@ -136,7 +136,7 @@ class Efl.Net.Server.Fd (Efl.Loop.Fd, Efl.Net.Server) { client file descriptor. ]] params { - client_fd: int; [[The file descriptor of the client socket. It comes preconfigured with close_on_exec. On failure, remember to close this socket]] + client_fd: int; [[The file descriptor of the client socket. It comes preconfigured with close_on_exec. On failure, remember to close this socket.]] } } diff --git a/src/lib/ecore_con/efl_net_server_simple.eo b/src/lib/ecore_con/efl_net_server_simple.eo index 3dbd3ce..0b76579 100644 --- a/src/lib/ecore_con/efl_net_server_simple.eo +++ b/src/lib/ecore_con/efl_net_server_simple.eo @@ -1,8 +1,8 @@ class Efl.Net.Server.Simple (Efl.Loop.Consumer, Efl.Net.Server) { [[A network server wrapper that creates clients based on @Efl.Net.Socket.Simple. - This is just a wrapper server, it will take an actual server - using @.inner_server or create one using @.inner_class. + This is just a wrapper server. It takes an actual server + using @.inner_server or creates one using @.inner_class. @since 1.19 ]] @@ -10,12 +10,12 @@ class Efl.Net.Server.Simple (Efl.Loop.Consumer, Efl.Net.Server) { @property inner_class { [[The class used to create @.inner_server if none was provided. - This class must be set at construction time and will be + This class must be set at build time and will be used to create the inner socket during @Efl.Object.finalize. - It is a helper for users, removing the burden to - manually create and specify a dialer object. + It is a helper for users, saving them the trouble of + manually creating and specifying a dialer object. ]] get { [[The internal class used to create the inner dialer.]] diff --git a/src/lib/ecore_con/efl_net_server_udp.eo b/src/lib/ecore_con/efl_net_server_udp.eo index 4fe4566..e8ad012 100644 --- a/src/lib/ecore_con/efl_net_server_udp.eo +++ b/src/lib/ecore_con/efl_net_server_udp.eo @@ -9,8 +9,8 @@ class Efl.Net.Server.Udp (Efl.Net.Server.Ip) { [[Avoids sent UDP packets being routed by a gateway, limiting them to the local network. This will use SO_DONTROUTE option to avoid gateways - routing sent packets to outside of local network. It's - useful for some protocols that only want local area to + routing sent packets to outside the local network. It's + useful for some protocols that only want the local area to be affected. ]] get { } diff --git a/src/lib/ecore_con/efl_net_server_udp_client.eo b/src/lib/ecore_con/efl_net_server_udp_client.eo index e311972..f8ecc8b 100644 --- a/src/lib/ecore_con/efl_net_server_udp_client.eo +++ b/src/lib/ecore_con/efl_net_server_udp_client.eo @@ -2,8 +2,8 @@ class Efl.Net.Server.Udp.Client (Efl.Object, Efl.Net.Socket) { [[A UDP client child of Efl.Net.Server.Udp Unlike connection protocols such as TCP or Local, UDP doesn't - create extra sockets for its "clients". Then this thin class - will provide the required socket interface on top of the server + create extra sockets for its "clients". This thin class + will then provide the required socket interface on top of the server internal socket. Given this limitation, some features such as 'cork' (used to diff --git a/src/lib/ecore_con/efl_net_server_unix.eo b/src/lib/ecore_con/efl_net_server_unix.eo index 69a3e39..f521fda 100644 --- a/src/lib/ecore_con/efl_net_server_unix.eo +++ b/src/lib/ecore_con/efl_net_server_unix.eo @@ -1,10 +1,10 @@ class Efl.Net.Server.Unix (Efl.Net.Server.Fd) { [[An AF_UNIX server. - The @Efl.Net.Server.serve method will call bind(2) directly, - thus path will be accessed and created in that method. If the + The @Efl.Net.Server.serve method will call bind(2) directly. + This means the path will be accessed and created in that method. If the created socket must be subject to some special mode or user, - change before executing that method, for example calling + change before executing said method, for example by calling umask(2). @since 1.19 @@ -12,7 +12,7 @@ class Efl.Net.Server.Unix (Efl.Net.Server.Fd) { methods { @property unlink_before_bind { - [[AF_UNIX paths may be stale due crashes, remove files and try again. + [[AF_UNIX paths may be stale due to crashes. Remove files and try again. If this property is $true, then it will unlink() before bind() is done, repeating this process if EADDRINUSE. @@ -25,7 +25,7 @@ class Efl.Net.Server.Unix (Efl.Net.Server.Fd) { } @property leading_directories_create { - [[If $true, all parent directories will be created with given mode. + [[If $true, all parent directories will be created with the given mode. This is only effective before @Efl.Net.Server.serve is called as it is used from inside that method. diff --git a/src/lib/ecore_con/efl_net_server_windows.eo b/src/lib/ecore_con/efl_net_server_windows.eo index 00c4ee2..88d034b 100644 --- a/src/lib/ecore_con/efl_net_server_windows.eo +++ b/src/lib/ecore_con/efl_net_server_windows.eo @@ -1,10 +1,10 @@ class Efl.Net.Server.Windows (Efl.Loop.Consumer, Efl.Net.Server) { [[A Windows NamedPipe server. - The @Efl.Net.Server.serve method will call CreateNamedPipe() - directly, thus path will be accessed and created in that + The @Efl.Net.Server.serve method calls CreateNamedPipe() + directly, so the path will be accessed and created in that method. If the created socket must be subject to some special - mode or user, change before executing that method. + mode or user, change before executing said method. @since 1.19 ]] diff --git a/src/lib/ecore_con/efl_net_session.eo b/src/lib/ecore_con/efl_net_session.eo index a6adf93..6ae9db2 100644 --- a/src/lib/ecore_con/efl_net_session.eo +++ b/src/lib/ecore_con/efl_net_session.eo @@ -3,9 +3,9 @@ enum Efl.Net.Session.State { @since 1.19 ]] - offline, [[No access point is connected]] - local, [[At least one access point was connected and the internet connectio wasn't verified]] - online, [[At least one access point was connected and the internet was verified]] + offline, [[No access point is connected.]] + local, [[At least one access point has connected and the internet connection hasn't been verified.]] + online, [[At least one access point has connected and the internet connection has been verified.]] } /* keep in sync with efl_net_control_technology.eo, comment what doesn't make sense */ @@ -32,15 +32,15 @@ class Efl.Net.Session (Efl.Loop.Consumer) { This API is targeted at applications that need access to the network, specifying the allowed bearer technologies to connect - to the internet, as well as if just local networking is enough + to the internet, as well as whether local networking is enough or validated internet access is required. - Some platforms may not implement the backend for this class, in - such cases the system will report always @.state "online" + Some platforms may not implement the backend for this class. In + this cases the system will report always @.state "online" (@Efl.Net.Session.State.online) and other properties will be NULL, such as @.name, @.interface, @.ipv4 and @.ipv6; as well as - @.technology is set to @Efl.Net.Session.Technology.unknown. Thus - if there is need to detect for an actual backend, check if the + @.technology is set to @Efl.Net.Session.Technology.unknown. As such + if you need to detect for an actual backend, check if the state is online but those properties are NULL or technology is unknown. @@ -58,10 +58,10 @@ class Efl.Net.Session (Efl.Loop.Consumer) { connect { [[Asks the session to be connected. - This method doesn't need to be called if all an - application want is to monitor the connectivity state, - like a poller that will only try to access the - webservice when there is an existing connection without + This method doesn't need to be called if an + application only needs to monitor the connectivity state, + such as a poller which will only try to access the + webservice when there is an existing connection, without triggering one. This method is subject to backend policy. For instance, @@ -78,7 +78,7 @@ class Efl.Net.Session (Efl.Loop.Consumer) { [[Indicates this session doesn't need a connection anymore. This reverses the effect of @.connect, let the system - disconnect if nothing else needs a connection. One may + disconnect if nothing else needs a connection. You can still use the session object to monitor the connectivity state via properties and "changed" event. ]] diff --git a/src/lib/ecore_con/efl_net_socket.eo b/src/lib/ecore_con/efl_net_socket.eo index e7be445..0039411 100644 --- a/src/lib/ecore_con/efl_net_socket.eo +++ b/src/lib/ecore_con/efl_net_socket.eo @@ -1,12 +1,12 @@ interface Efl.Net.Socket (Efl.Io.Reader, Efl.Io.Writer, Efl.Io.Closer) { [[The basic socket interface. - It is built upon the three core Input/Output interfaces: + This is built upon the three core Input/Output interfaces: - @Efl.Io.Reader: to receive data. - @Efl.Io.Writer: to send data. - @Efl.Io.Closer: to close the socket for further operations. - Thus it can be used with utilities like @Efl.Io.Copier. + As such it can be used with utilities like @Efl.Io.Copier. @since 1.19 ]] @@ -14,12 +14,12 @@ interface Efl.Net.Socket (Efl.Io.Reader, Efl.Io.Writer, Efl.Io.Closer) { @property address_local { [[The local address, similar to getsockname(). - The actual value depends on the type of socket, like an + The actual value depends on the type of socket, such as an IPv4 (ip:port) or IPv6 ([ip]:port) formatted for a TCP/UDP socket, the path if an Unix Local... - It's always resolved, then if operations are working - with domain names or URL, this is the values the kernel + It's always resolved. If operations are working + with domain names or URLs, these are the values the kernel reports. It's similar to getsockname() in behavior. ]] get { } @@ -36,8 +36,8 @@ interface Efl.Net.Socket (Efl.Io.Reader, Efl.Io.Writer, Efl.Io.Closer) { IPv4 (ip:port) or IPv6 ([ip]:port) formatted for a TCP/UDP socket, the path if an Unix Local... - It's always resolved, then if operations are working - with domain names or URL, this is the values the kernel + It's always resolved. If operations are working + with domain names or URLs, these are the values the kernel reports. It's similar to getpeername() in behavior. ]] get { } diff --git a/src/lib/ecore_con/efl_net_socket_simple.eo b/src/lib/ecore_con/efl_net_socket_simple.eo index d7260a8..d233096 100644 --- a/src/lib/ecore_con/efl_net_socket_simple.eo +++ b/src/lib/ecore_con/efl_net_socket_simple.eo @@ -1,16 +1,16 @@ class Efl.Net.Socket.Simple (Efl.Io.Buffered_Stream, Efl.Net.Socket) { [[A wrapper socket offering an easy to use, buffered I/O. - The simple socket encapsulates an actual @Efl.Net.Socket, and + The simple socket encapsulates an actual @Efl.Net.Socket and uses it with an @Efl.Io.Buffered_Stream, which creates an input - @Efl.Io.Queue, an output @Efl.Io.Queue and these are linked + @Efl.Io.Queue and an output @Efl.Io.Queue. These are linked using a receiver and a sender @Efl.Io.Copier. - The idea is that unlike traditional @Efl.Net.Socket that will - attempt to write directly to socket and thus may take less data + The idea is that unlike the traditional @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 it - @Efl.Io.Writer.can_write. That makes its operation much simpler + buffer, feeding to the actual socket when + @Efl.Io.Writer.can_write. This makes its operation much simpler as @Efl.Io.Writer.write will always take the full data -- allows "write and forget", if unlimited (see @Efl.Io.Buffered_Stream.max_queue_size_output). @@ -23,8 +23,8 @@ class Efl.Net.Socket.Simple (Efl.Io.Buffered_Stream, Efl.Net.Socket) { @Efl.Io.Buffered_Stream.discard or @Efl.Io.Buffered_Stream.clear. - Then when waiting for a complete message, just peek at its - contents, if not complete do nothing, if complete then either + When waiting for a complete message, you can just peek at its + contents: if incomplete do nothing, if complete then use either @Efl.Io.Reader.read to get a copy or manipulate a read-only reference from @Efl.Io.Buffered_Stream.slice and then @Efl.Io.Buffered_Stream.discard diff --git a/src/lib/ecore_con/efl_net_socket_ssl.eo b/src/lib/ecore_con/efl_net_socket_ssl.eo index b9a9020..ddab2f4 100644 --- a/src/lib/ecore_con/efl_net_socket_ssl.eo +++ b/src/lib/ecore_con/efl_net_socket_ssl.eo @@ -4,8 +4,8 @@ var Efl.Net.Socket.Ssl.Error.CERTIFICATE_VERIFY_FAILED: Eina.Error; [[Failed to class Efl.Net.Socket.Ssl (Efl.Loop.Consumer, Efl.Net.Socket) { [[A wrapper socket doing SSL (Secure Sockets Layer). - Use this wrapper around an existing socket to do secure - communication, a common use is to apply it to TCP sockets + Use this wrapper around an existing socket for secure + communication. One common use is to apply it to TCP sockets created with @Efl.Net.Dialer.Tcp or @Efl.Net.Server.Tcp created with "client,add" event. @@ -13,7 +13,7 @@ class Efl.Net.Socket.Ssl (Efl.Loop.Consumer, Efl.Net.Socket) { ]] events { - ssl,ready; [[Notifies the SSL handshake was done and the socket is now able to communicate]] + ssl,ready; [[Notifies the SSL handshake has been performed and the socket is now able to communicate]] ssl,error: Eina.Error; [[An error such as @Efl.Net.Socket.Ssl.Error.HANDSHAKE]] } diff --git a/src/lib/ecore_con/efl_net_socket_udp.eo b/src/lib/ecore_con/efl_net_socket_udp.eo index de221fa..539dfd2 100644 --- a/src/lib/ecore_con/efl_net_socket_udp.eo +++ b/src/lib/ecore_con/efl_net_socket_udp.eo @@ -7,7 +7,7 @@ class Efl.Net.Socket.Udp (Efl.Net.Socket.Fd) { created by an dialer. Since for the server 'clients' there is no accepted connection - it will reuse the same file decriptor and to avoid it being + it will reuse the same file decriptor. To avoid it being closed, another class Efl.Net.Server.Udp.Client is used instead. @since 1.19 @@ -38,8 +38,8 @@ class Efl.Net.Socket.Udp (Efl.Net.Socket.Fd) { [[Avoids sent UDP packets being routed by a gateway, limiting them to the local network. This will use SO_DONTROUTE option to avoid gateways - routing sent packets to outside of local network. It's - useful for some protocols that only want local area to + routing sent packets outside the local network. It's + useful for some protocols that only want the local area to be affected. ]] get { } @@ -147,7 +147,7 @@ class Efl.Net.Socket.Udp (Efl.Net.Socket.Fd) { [[Forces binding to a specific address. Some servers may request packets being sent from a - specific address, then one should bind to that address + specific address, then one binds to that address before proceeding to dial. If no address is provided or bind is not called, a @@ -166,7 +166,7 @@ class Efl.Net.Socket.Udp (Efl.Net.Socket.Fd) { } init @protected { - [[Initializes the socket to communicate with given IP address]] + [[Initializes the socket to communicate with a given IP address]] params { remote_address: Efl.Net.Ip_Address; [[The remote address this socket will communicate with]] } -- 2.7.4