Difference between revisions of "lNet"

From Lazarus wiki
Jump to navigationJump to search
("Usage" and "Documentation" sections moved to beginning of article)
(22 intermediate revisions by 9 users not shown)
Line 1: Line 1:
== About ==
+
==About==
lNet or Lightweight Networking Library is a collection of classes and components to enable event-driven TCP or UDP networking. lNet is released under a modified LGPL license. (permits static linking)
+
'''lNet''' or '''Lightweight Networking Library''' is a collection of classes and components to enable event-driven TCP or UDP networking.
  
{{Web and Networking Programming}}
+
Authors:
 +
* Ales Katona ([[User: Almindor]])
 +
* Micha Nelissen
  
== Overview ==
+
License: modified LGPL license (permits static linking).
Homepage of the lNet base libraries is: http://lnet.wordpress.com
 
  
<b>Contains:</b><br>
+
==Download==
The package consists of base lNet units library, lTelnet for telnet protocol, lFTP for ftp protocol and lNetComponents libraries for providing visual and non-visual components for networking. As of 0.4.0 lHTTP and lSMTP components have been added. Since 0.5.1 there's a MIME support as part of the library mainly for creation of multipart messages for SMTP. Since 0.6.0 lNet supports SSL in a modular way, and SMTP protocol has been extended to full support of SSL/TLS (including runtime STARTTLS negotiation). HTTPS client side is supported too.
+
There are two variants of the library, which are no longer completely synchronised:
  
<b>Tested on:</b><br>
+
* [http://sourceforge.net/projects/lazarus-ccr/files/lNet/ lNet package]. Packaged as utilities for the use of the FPC project itself. They are not recommended for general use.
The non-visual console components were tested on Win32, Win64, Linux_x86_32, Linux_x86_64, Linux_PPC, Linux_PPC_64, Linux_ARM* (2.1.4+) and FreeBSD_x86_32.
+
* At http://lnet.wordpress.com, however this advises that the project has been moved to GitHub https://github.com/almindor/lnet.
The visual (lazarus packages) components were tested in Win32, Win64, arm/WinCE, Linux_x86_32, Linux_x86_64 and FreeBSD_x86_32. (gtk1 and gtk2 on unix platforms)
 
  
<b>Short history:</b><br>
+
SVN: http://svn.freepascal.org/svn/fpcprojects/lnet
As of version 0.3 the package is only single-threaded. I've dropped multithreaded version and now use exclusively LCL [[Main_Loop_Hooks | features]] to work.
 
  
As of version 0.4 the package has "eventers" which enable per-OS optimalizations and additional flexibility including watching for events on files additionaly to the sockets.
+
You can contact the author directly by email or go to #lnet channel on freenode.
  
Version 0.5 changed some high level higher protocol API (ftp, http etc.)
+
== Usage ==
  
Since 0.5.1 WinCE is considered an unstable but supported platform.
+
Drop a TLTCPComponent or TLUDPComponent on a form. Assign OnAccept, OnError, OnReceive, OnConnect and OnDisconnect event handlers. Note that this is optional but in most
 +
cases required for functionality.
  
Version 0.6 is highly compatible to previous releases.
+
Client connection is initialized with the Connect call. Arguments are IP address/hostname and port respectivly. Non-blocking connect is used, this means that you '''DON'T''' know that you're connected until OnConnect event is fired.
  
* ARM/Linux fpc 2.1.4 has a bug with -O2 causing lNet to crash. Compile without optimizations on this platform.
+
Server connection is initialized with the Listen* call. Argument is port.
  
== Authors ==
+
{{Note| address is a string representation of IP eg: '127.0.0.1' or a hostname like 'localhost'.}}
Ales Katona ([[User: Almindor]])<br>
 
Micha Nelissen
 
  
== License ==
+
Sending data to the other side is accomplished with the Send/SendMessage method.
Modified LGPL (read LICENSE and LICENSE.ADDON included in package).
 
  
== Contact ==
+
===Events of TLNetComponent===
You can contact me directly by email or go to #lnet channel on freenode.
 
  
== News ==
+
* OnError - this event is fired whenever a connection error occurs. If no handler is assigned an excepion with "msg" is raised. Arguments are: msg - contains string and numerical representation of error message formatted in native encoding or UTF8 (depending on ForceUTF8 property). aSocket is the socket at which the error occured, nil means that the error is not a socket specific one.
  
13th of March 2011:<br><hr>
+
* OnConnect - This event is fired when the client succesfuly connects. aSocket is the socket which connected. It should serve as the "start" point for clients.
  
A new version of lNet was just released. 0.6.5 completes SSL and IPv6 support including server-side and per-socket (for SSL) setting. SSL and IPv6 bugs were fixed as well as some remaining disconnect problems related to server bind errors and lingering sockets. DecodeURL bug introduced in 0.6.4 was also fixed.
+
* OnAccept - this event is fired whenever a connection is accepted on a server. If no handler is assigned nothing is done. aSocket contains the socket which accepted the connection.
  
9th of May 2010:<br><hr>
+
* OnDisconnect - this event is fired whenever a connection is lost. If no handler is assigned nothing is done. aSocket contains the socket which got disconnected.
  
A new version of lNet was just released. 0.6.4 adds Qt4 support inside Lazarus (lazarus latest trunk needed, 0.9.30 should be 1st stable with it). There were also numerous fixes (http URL parsing, FTP problems) and one major bug fixed (WinCE compilation with FPC 2.4.0+). Grab it at SVN, packages will be uploaded ASAP.
+
* OnReceive - This event is fired whenever new data is '''ready to be received'''. If no handler is assigned nothing is done, but a system buffer fill may happen which will in turn fire an OnError event. aSocket is the socket at which the data got received. Data is read by Get/GetMessage method.
  
13th of February 2010:<br><hr>
+
* OnCanSend - This event is fired whenever new data can be sent again on a socket, after a call to send function failed, returning 0. It can be used to automate sending of big chunks. aSocket is socket on which send can be called.
  
Well there’s a skip in dates. Anyways version 0.6.3 of lNet has been released, you can find it in the downloads section. There’s been various bugfixes and file renames to avoid FPC conflicts. I didn’t find the time to do the QT4 port as I wanted but it’s in the works now. Some SSL fixes were made as well.
+
== Documentation ==
  
30th of May 2008:<br><hr>
+
Documentation of lNet is partially done. You can also use Jesus' diagrams of classes and units as basic reference.
  
Where to begin? This is a HUGE critical bugfix release. There was about 5 big bugs fixed in SSL section, one logical oversight in Session support. OpenSSL unit was added so WinCE compiles again and SMTP and FTP got bugs fixed in regards to possible desynchronization. I'd urge everyone who uses 0.6.x to update ASAP, but some bugs are also from 0.5.x (specifically the SMTP and FTP event deadlock problem).
+
Documentation of eventer and TCP/UDP protocols: http://members.chello.sk/ales/docs<br>
  
For more information on the various bugs, please see the [http://lnet.wordpress.com/blog/ lNet blog].
+
Overview diagrams can be found here: http://members.chello.sk/ales/docs/diagrams/overview.html<br>
 +
Pictures: <br>
 +
[http://members.chello.sk/ales/docs/diagrams/inheritance_composition.png New class diagram]<br>
 +
[http://members.chello.sk/ales/docs/diagrams/extra/allclasses.png All classes]<br>
 +
[http://members.chello.sk/ales/docs/diagrams/extra/lnetunits.png lNet units]<br>
 +
[http://members.chello.sk/ales/docs/diagrams/extra/lnetunits2.png lNet units 2]<br>
  
18th of May 2008:<br><hr>
+
Docs Mirror and Ongoing Notes: http://z505.com/cgi-bin/powtils/docs/1.6/idx.cgi?file=lnetlufdoc
  
It seems that due to an oversight in what's packaged with FPC and for which platform, lNet 0.6.x doesn't currently compile on WinCE
+
== Installation ==
due to missing OpenSSL unit. The unit is in fpc 2.2.0, but is not compiled for that platform yet (it is in 2.2.1+). I will add
+
LNet 0.5+:
the unit to lNet and release 0.6.2 shortly, but until then, WinCE users can work around this by copying [http://svn.freepascal.org/svn/fpc/trunk/packages/openssl/src/openssl.pas this file] into
+
* In the lazarus/components directory, unzip the files from lnet-<version>.zip file. The lnet-<version> folder will be created.
their lnetdir/lib directory. (same will be done in 0.6.2 so don't worry)
+
* Open Lazarus
 +
* Open the package lnet-<version>/lazaruspackage/lnetvisual.lpk with Package/Open package file (.lpk)
 +
* Click on Use/Install and answer 'Yes' when you are asked about Lazarus rebuilding. A new tab named 'lNet' will be created in the components palette.
 +
{{Note| users who don't want to depend on LCL but use LNet in Lazarus (non-visually), can just compile lnetbase.lpk, which adds all the base units to path.}}
  
26th of April 2008:<br><hr>
+
LNet 0.4:
 +
* In the lazarus/components directory, unzip the files from lnet-<version>.zip file. The lnet-<version> folder will be created.
 +
* Open Lazarus
 +
* Open the package lnet-<version>/lazaruspackage/lnetpackage.lpk with Package/Open package file (.lpk)
 +
* Click on Compile
 +
* Open the package lnet-<version>/lazaruspackage/ide/lnetidepackage.lpk with Package/Open package file (.lpk)
 +
* Click on Use/Install and answer 'Yes' when you are asked about Lazarus rebuilding. A new tab named 'lNet' will be created in the components palette.
 +
{{Note| older lNet is extraced to "lnetpackage" dir. Since 0.4.0 the "visual" and "non visual" packages are in one distribution file.}}
  
0.6.1 has been released today. This release fixes an ugly SSL logical bug in regards to the mandatory requirements of Certificate Authority List file and Keyfile proprties of SSLSession. They are no longer needed for normal SSL to work. A minor change in HTTP and handling of SSLSession are also present.
+
==Package contents==
 +
The package consists of base lNet units library, lTelnet for telnet protocol, lFTP for ftp protocol and lNetComponents libraries for providing visual and non-visual components for networking. As of 0.4.0 lHTTP and lSMTP components have been added. Since 0.5.1 there's a MIME support as part of the library mainly for creation of multipart messages for SMTP. Since 0.6.0 lNet supports SSL in a modular way, and SMTP protocol has been extended to full support of SSL/TLS (including runtime STARTTLS negotiation). HTTPS client side is supported too.
  
Bugfix release.
+
==Testing==
 
+
The non-visual console components were tested on Win32, Win64, Linux_x86_32, Linux_x86_64, Linux_PPC, Linux_PPC_64, Linux_ARM* (2.1.4+) and FreeBSD_x86_32.
20th of April 2008:<br><hr>
+
The visual (Lazarus packages) components were tested in Win32, Win64, ARM/WinCE, Linux_x86_32, Linux_x86_64 and FreeBSD_x86_32. (gtk1 and gtk2 on unix platforms)
 
 
0.6.0 has been released! Adding full client-side SSL support (via OpenSSL library) in a modular way. SMTP and HTTP (client) protocols have been already modified to support new features.
 
 
 
23th of March 2008:<br><hr>
 
 
 
0.6.0 is getting closer now, SSL/HTTPS is working (client side) already.
 
Added a [http://members.chello.sk/ales/docs/diagrams/inheritance_composition.png new class diagram] to the documentation section.
 
 
 
15th of November 2007:<br><hr>
 
 
 
Released 0.5.8a as minor bugfix release. Bugs:
 
* fixed compilation of winCE lnet
 
* fixed missing override in TLCLEventer.Create
 
 
 
Bugfix release.
 
 
 
16th of September 2007:<br><hr>
 
 
 
Released 0.5.8 as bugfix release. Bugs:
 
* fixed crash in visual lnet package in windows if .Disconnect before .Free
 
* fixed SMTP RFC compliance on DATA (fixed problems on some servers)
 
* fixed/updated SMTP linebreaks (74 to 1000 and bugfix)
 
 
 
Bugfix release.
 
 
 
20th of August 2007:<br><hr>
 
 
 
Released 0.5.7 as bugfix release. Bugs:
 
* fixed using of MSG_NOSIGNAL in Darwin (uses SO_NOSIGPIPE now instead)
 
* fixed forgotten commit of Timeout changes from 0.5.5 (doh!)
 
* introduced safety locks on CallAction against recursion
 
 
 
Bugfix release.
 
 
 
04th of August 2007:<br><hr>
 
 
 
Released 0.5.6 as bugfix release. Bugs:
 
* fixed potential UDP access violation with Disconnect in rare situations
 
* fixed loss of error numbers with TLSocket.Get and TLSocket.Send
 
* updated linux epoll presence detection (no longer uses uname)
 
 
 
Bugfix release.
 
 
 
15th of July 2007:<br><hr>
 
 
 
Released 0.5.5 as bugfix release. Bugs:
 
* fixed TCP.IterReset (now comforming to docs, see API changes for more info)
 
* changed .Timeout on all components to be signed, whereas -1 now means "block indefenetly until an event happens"
 
* fixed documentation errata mainly about IterNext
 
 
 
8th of July 2007:<br><hr>
 
 
 
Released 0.5.4 as bugfix release. Bugs:
 
* fixed TCP.Count (returned always 1 before)
 
* fixed UDP.Listen and UDP.Connect (caused AV in certain situations)
 
* fixed potential bugs with TLSocket.Bail calls (didn't exit originating function)
 
 
 
25th of June 2007:<br><hr>
 
 
 
Released 0.5.3 as bugfix release. Bugs:
 
* FTP active mode bug fixed
 
* removed visual property Timeout (irrelevant in Lazarus/visual)
 
* fixed FTP property TransferMethod (default was wrong so it never saved in OI)
 
* fixed TCP Iterator bug if used right after Listen() (was nil, now points to server socket)
 
* fixed LocalAddress and LocalPort values (were byte order flipped)
 
 
 
11th of June 2007:<br><hr>
 
 
 
Released 0.5.2 as bugfix release. Fixed a windows and winCE bug in LCLEventer which could cause memory corruption in special cases.
 
 
 
1st of June 2007:<br><hr>
 
 
 
Released 0.5.1 according to schedule. New stuff:<br>
 
* fixed an oversight in WinCE visual interface (didn't work in 0.5.0)
 
* fixed some potential FTP and SMTP bugs (minor)
 
* added MIME support mainly for creation of complex mails to send with SMTP (attachments etc.)
 
 
 
This release has been mainly concentrated on the MIME support, the other issues are bug fixes and/or maintenance.
 
  
14th of April 2007:<br><hr>
+
==History==
  
Released 0.5.0 not according to schedule. New stuff:<br>
+
* March 2011: A new version of lNet was just released. 0.6.5 completes SSL and IPv6 support including server-side and per-socket (for SSL) setting. SSL and IPv6 bugs were fixed as well as some remaining disconnect problems related to server bind errors and lingering sockets. DecodeURL bug introduced in 0.6.4 was also fixed.
* fixed some ugly UDP bugs
 
* fixed windows blocking problems with visual lNet (dialogs and menus blocked our events)
 
* API cleanups (WARNING: See [[lNet#API changes |here]])
 
* preliminary winCE support with Lazarus/fpc cross compilation (alpha)
 
* simplified Lazarus packaging, see [[lNet#Installation |Installation]] for more info
 
  
This is mostly a bugfix and stabilization release. Many planned features got dropped until we got something we felt right with. Sorry for the delay as well but school was keeping me quite occupied lately.
+
* May 2010: A new version of lNet was just released. 0.6.4 adds Qt4 support inside Lazarus (lazarus latest trunk needed, 0.9.30 should be 1st stable with it). There were also numerous fixes (http URL parsing, FTP problems) and one major bug fixed (WinCE compilation with FPC 2.4.0+). Grab it at SVN, packages will be uploaded ASAP.
  
== Download ==
+
* February 2010: Well there’s a skip in dates. Anyways version 0.6.3 of lNet has been released, you can find it in the downloads section. There’s been various bugfixes and file renames to avoid FPC conflicts. I didn’t find the time to do the QT4 port as I wanted but it’s in the works now. Some SSL fixes were made as well.
  
* [http://sourceforge.net/projects/lazarus-ccr/files/lNet/| lNet package]
+
* May 2008: Where to begin? This is a HUGE critical bugfix release. There was about 5 big bugs fixed in SSL section, one logical oversight in Session support. OpenSSL unit was added so WinCE compiles again and SMTP and FTP got bugs fixed in regards to possible desynchronization. I'd urge everyone who uses 0.6.x to update ASAP, but some bugs are also from 0.5.x (specifically the SMTP and FTP event deadlock problem).
  
* SVN: http://svn.freepascal.org/svn/fpcprojects/lnet
+
* May 2008: It seems that due to an oversight in what's packaged with FPC and for which platform, lNet 0.6.x doesn't currently compile on WinCE due to missing OpenSSL unit. The unit is in fpc 2.2.0, but is not compiled for that platform yet (it is in 2.2.1+). I will add the unit to lNet and release 0.6.2 shortly, but until then, WinCE users can work around this by copying [http://svn.freepascal.org/svn/fpc/trunk/packages/openssl/src/openssl.pas this file] into their lnetdir/lib directory. (same will be done in 0.6.2 so don't worry)
  
== Change Log ==
+
* April 2008: 0.6.1 has been released today. This release fixes an ugly SSL logical bug in regards to the mandatory requirements of Certificate Authority List file and Keyfile proprties of SSLSession. They are no longer needed for normal SSL to work. A minor change in HTTP and handling of SSLSession are also present.
* Version 0.6.5 completed SSL server support. Completed IPv6. Fixed DecodeURL problems and disconnect bugs
 
* Version 0.6.4 added Qt4 support in visual, compilation fix on WinCE in later FPC versions, lots of small fixes
 
* Version 0.6.3 compilation fix with later FPC versions fixing problem with openssl unit
 
* Version 0.6.2 huge bugfix release, fixes Sessions, SSL, SMTP and FTP bugs including some example bugs
 
* Version 0.6.1 bugfix release regarding CAFile and KeyFile properties of SSLSession
 
* Version 0.6.0 new major release adds SSL client-side support
 
* Version 0.5.8 bugfix release regarding windows visual version and SMTP RFC compliance
 
* Version 0.5.7 bugfix release regardin Darwin (MSG_NOSIGNAL was wrongly used)
 
* Version 0.5.6 bugfix release regarding UDP disconnect bugs and few others
 
* Version 0.5.5 bugfix release regarding TCP IterReset, and some docs. Changed timeout to signed.
 
* Version 0.5.4 bugfix release regarding UDP listen/connect and TCP.Count
 
* Version 0.5.3 bugfix release regarding FTP and some TCP fixes
 
* Version 0.5.2 bugfix release fixing windows and winCE LCLEventer
 
* Version 0.5.1 MIME support and WinCE fixes
 
* Version 0.5.0 stabilization and API cleanups
 
* Version 0.4.0 complete overhaul and new components
 
* Version 0.3.1-1 30.01.2006 (fixed a fixes bug in Linux version, should compile now)
 
* Version 0.3.1 27.01.2006
 
* Version 0.3.0 (2.4.0) 16.01.2006
 
* Version 0.2.0 29.11.2005
 
* Version 0.1.0 12.11.2005
 
  
== Status ==
+
== Stability ==
  
 
* Base lNet TCP/UDP - stable
 
* Base lNet TCP/UDP - stable
Line 203: Line 111:
 
* IPv6 support - stable (0.6.5+)
 
* IPv6 support - stable (0.6.5+)
  
<nowiki>*</nowiki> FTP and Telnet still need some additional features like authentification methods.<br>
+
<nowiki>*</nowiki> FTP and Telnet still need some additional features like authentication methods.
 +
 
 +
On Linux, since you start using LNet, GDB can crash randomly (upon compilations) with diverse kind of reports. Setting debugger to Automatic in both lnetbase and lnetvisual package's options fixes the issue.
  
 
== Roadmap ==
 
== Roadmap ==
Line 223: Line 133:
 
<nowiki>*</nowiki> PING requires raw sockets which are only accessible to root on unix/linux platforms. It was decided that lNet won't support this, users who need PING should use the ping and ping6 programs via TProcess.
 
<nowiki>*</nowiki> PING requires raw sockets which are only accessible to root on unix/linux platforms. It was decided that lNet won't support this, users who need PING should use the ping and ping6 programs via TProcess.
  
== Dependencies / System Requirements ==
+
== Requirements ==
<b>LNet 0.6+</b><br>
+
LNet 0.6+:
 
* Lazarus 0.9.24+ and FPC 2.2.0+
 
* Lazarus 0.9.24+ and FPC 2.2.0+
 
 
* Status: Beta
 
* Status: Beta
 +
* Issues: Completely tested on Windows (WinXP), Linux (Ubuntu 7.10). FastCGI considered broken for now.
  
* Issues: Completly tested on Windows (WinXP), Linux (Ubuntu 7.10). FastCGI considered broken for now.
+
LNet 0.5:
 
 
<b>LNet 0.5</b><br>
 
 
* Lazarus 0.9.22+ and FPC 2.0.4+
 
* Lazarus 0.9.22+ and FPC 2.0.4+
 
 
* Status: Beta
 
* Status: Beta
 +
* Issues: Completely tested on Windows (WinXP), Linux (Ubuntu 6.10) and FreeBSD 5.5. FastCGI considered broken for now. <b>WinCE requires Lazarus 0.9.23+ to compile!</b>
  
* Issues: Completly tested on Windows (WinXP), Linux (Ubuntu 6.10) and FreeBSD 5.5. FastCGI considered broken for now. <b>WinCE requires Lazarus 0.9.23+ to compile!</b>
+
LNet 0.4:
<b>LNet 0.4</b><br>
 
 
* Lazarus 0.9.18+ and FPC 2.0.4+
 
* Lazarus 0.9.18+ and FPC 2.0.4+
 
 
* Status: Beta
 
* Status: Beta
 
 
* Issues: Completely tested on Windows (WinXP), Linux (Ubuntu 6.06LTS) and FreeBSD 6.1. HTTP server has issues under high load with fastcgi usage. FastCGI works only in Linux for now.
 
* Issues: Completely tested on Windows (WinXP), Linux (Ubuntu 6.06LTS) and FreeBSD 6.1. HTTP server has issues under high load with fastcgi usage. FastCGI works only in Linux for now.
  
== Installation ==
+
=== Ubuntu special notice ===
<b>LNet 0.5+:</b><br>
 
* In the lazarus/components directory, unzip the files from lnet-<version>.zip file. The lnet-<version> folder will be created.
 
* Open lazarus
 
* Open the package lnet-<version>/lazaruspackage/lnetvisual.lpk with Component/Open package file (.lpk)
 
* Click on Install and answer 'Yes' when you are asked about Lazarus rebuilding. A new tab named 'lNet' will be created in the components palette.<br>
 
<br>
 
{{Note| users who don't want to depend on LCL but use LNet in Lazarus (non-visually), can just compile lnetbase.lpk, which adds all the base units to path.}}
 
 
 
<b>LNet 0.4:</b><br>
 
* In the lazarus/components directory, unzip the files from lnet-<version>.zip file. The lnet-<version> folder will be created.
 
* Open lazarus
 
* Open the package lnet-<version>/lazaruspackage/lnetpackage.lpk with Component/Open package file (.lpk)
 
* Click on Compile
 
* Open the package lnet-<version>/lazaruspackage/ide/lnetidepackage.lpk with Component/Open package file (.lpk)
 
* Click on Install and answer 'Yes' when you are asked about Lazarus rebuilding. A new tab named 'lNet' will be created in the components palette.<br>
 
<br>
 
{{Note| older lNet is extraced to "lnetpackage" dir. Since 0.4.0 the "visual" and "non visual" packages are in one distribution file.}}
 
 
 
== Ubuntu special notice ==
 
 
 
On Ubuntu, the Lazarus components folder is "/usr/lib/lazarus/components". You must copy the lNetpackage in this folder and unzip in this folder to generate the lnetpackage folder.
 
 
 
On this distribution you may have issues if you don't use the root account because you won't have write permissions on this folder...
 
Activate the root account management and log in with the root account before doing any operation.
 
 
 
Some "missing files" are, in fact, in the "/net" subfolder and are not found by the fpc compiler.
 
Simply copy missing files from the subfolder (lnet.pas, tomwinsock.pas, lfunc.inc...)
 
"/usr/lib/lazarus/components/lnetpackage/lnet" in the
 
"/usr/lib/lazarus/components/lnetpackage" folder.
 
Then complete the setup by following the installation procedure.
 
 
 
by Steph12358
 
 
 
== Documentation ==
 
 
 
Documentation of lNet is partially done. You can also use Jesus' diagrams of classes and units as basic reference.
 
  
Documentation of eventer and TCP/UDP protocols: http://members.chello.sk/ales/docs<br>
+
Some "missing files" are, in fact, in the "/net" subfolder and are not found by the fpc compiler. Simply copy missing files from the subfolder (lnet.pas, tomwinsock.pas, lfunc.inc...) "/usr/lib/lazarus/components/lnetpackage/lnet" in the "/usr/lib/lazarus/components/lnetpackage" folder (adjust paths as necessary). Then complete the setup by following the installation procedure. (by Steph12358)
 
 
Overview diagrams can be found here: http://members.chello.sk/ales/docs/diagrams/overview.html<br>
 
Pictures: <br>
 
[http://members.chello.sk/ales/docs/diagrams/inheritance_composition.png New class diagram]<br>
 
[http://members.chello.sk/ales/docs/diagrams/extra/allclasses.png All classes]<br>
 
[http://members.chello.sk/ales/docs/diagrams/extra/lnetunits.png lNet units]<br>
 
[http://members.chello.sk/ales/docs/diagrams/extra/lnetunits2.png lNet units 2]<br>
 
 
 
Docs Mirror and Ongoing Notes: http://z505.com/cgi-bin/powtils/docs/1.6/idx.cgi?file=lnetlufdoc
 
 
 
== Usage ==
 
 
 
''TCP/UDP''
 
 
 
Drop a TLTCPComponent or TLUDPComponent on a form.
 
Assign OnAccept, OnError, OnReceive, OnConnect and OnDisconnect event handlers. Note that this is optional but in most
 
cases required for functionality.
 
 
 
Client connection is initialized with the Connect call. Arguments are IP address/hostname and port respectivly. Non-blocking connect is used, this means that you '''DON'T''' know that you're connected until OnConnect event is fired.
 
 
 
Server connection is initialized with the Listen* call. Argument is port.
 
 
 
{{Note| address is a string representation of IP eg: '127.0.0.1' or a hostname like 'localhost'.}}
 
 
 
Sending data to the other side is accomplished with the Send/SendMessage method.
 
 
 
'''Events of TLNetComponent class.'''
 
 
 
* OnError - this event is fired whenever a connection error occurs. If no handler is assigned an excepion with "msg" is raised. Arguments are: msg - contains string and numerical representation of error message formatted in native encoding or UTF8 (depending on ForceUTF8 property). aSocket is the socket at which the error occured, nil means that the error is not a socket specific one.
 
 
 
* OnConnect - This event is fired when the client succesfuly connects. aSocket is the socket which connected. It should serve as the "start" point for clients.
 
 
 
* OnAccept - this event is fired whenever a connection is accepted on a server. If no handler is assigned nothing is done. aSocket contains the socket which accepted the connection.
 
 
 
* OnDisconnect - this event is fired whenever a connection is lost. If no handler is assigned nothing is done. aSocket contains the socket which got disconnected.
 
 
 
* OnReceive - This event is fired whenever new data is '''ready to be received'''. If no handler is assigned nothing is done, but a system buffer fill may happen which will in turn fire an OnError event. aSocket is the socket at which the data got received. Data is read by Get/GetMessage method.
 
 
 
* OnCanSend - This event is fired whenever new data can be sent again on a socket, after a call to send function failed, returning 0. It can be used to automate sending of big chunks. aSocket is socket on which send can be called.
 
  
 
== API changes ==
 
== API changes ==
  
 
'''0.1 to 0.2'''
 
'''0.1 to 0.2'''
There have been some API changes from 0.1 to 0.2. These were required and should improve the usability of packages. I know API changes are always a PITA but I'll try to keep them minimal from now on. Version 0.3 will be the first beta from which API will remain unchanged (only adding new stuff will be possible).
+
* There have been some API changes from 0.1 to 0.2. These were required and should improve the usability of packages. I know API changes are always a PITA but I'll try to keep them minimal from now on. Version 0.3 will be the first beta from which API will remain unchanged (only adding new stuff will be possible).
 
 
 
* OnRecieve() changed to OnReceive()
 
* OnRecieve() changed to OnReceive()
 
* Accept() changed to Listen()
 
* Accept() changed to Listen()
Line 337: Line 166:
  
 
'''0.3 to 0.4'''
 
'''0.3 to 0.4'''
Lots of additions. Only "breakage" is that TLSocket.Port got changed into TLSocket.LocalPort and TLSocket.PeerPort for consistency reasons.
+
* Lots of additions. Only "breakage" is that TLSocket.Port got changed into TLSocket.LocalPort and TLSocket.PeerPort for consistency reasons.
  
 
'''0.4 to 0.5'''
 
'''0.4 to 0.5'''
We did some API cleanup which resulted in API breakage.
+
* We did some API cleanup which resulted in API breakage.
 
* All "connection" classes now descend from TLComponent
 
* All "connection" classes now descend from TLComponent
 
* TLSocket now has a .Creator which is a TLComponent property specifying the creator (eg: TLTcp), so you can see now which socket in an event belongs to which connection.
 
* TLSocket now has a .Creator which is a TLComponent property specifying the creator (eg: TLTcp), so you can see now which socket in an event belongs to which connection.
Line 348: Line 177:
  
 
'''0.5.4- to 0.5.5+'''
 
'''0.5.4- to 0.5.5+'''
Some minor API changes were made which shouldn't break anything but I list them to be on the safe side.
+
* Some minor API changes were made which shouldn't break anything but I list them to be on the safe side.
 
* .Timeout property on eventers and connections was set to Integer (from DWord) to support -1 as "block until an event happens"
 
* .Timeout property on eventers and connections was set to Integer (from DWord) to support -1 as "block until an event happens"
  
 
'''0.5 to 0.6'''
 
'''0.5 to 0.6'''
No changes in public API, only additions.
+
* No changes in public API, only additions.
  
'''WARNING: '''
+
'''Note for 0.4.0''': In version 0.4.0, I forgot to move lHTTPSettings unit from lib to the http example. It was NOT supposed to be a part of the library, just the example. DON'T use this, it's not a "library", it's a part of the example (http server will get it's own project later)
In version 0.4.0, I forgot to move lHTTPSettings unit from lib to the http example. It was NOT supposed to be a part of the library, just the example. DON'T use this, it's not a "library", it's a part of the example (http server will get it's own project later)
 
  
 
[[Category:Components]]
 
[[Category:Components]]
 
[[Category:Networking]]
 
[[Category:Networking]]

Revision as of 12:08, 12 November 2020

About

lNet or Lightweight Networking Library is a collection of classes and components to enable event-driven TCP or UDP networking.

Authors:

License: modified LGPL license (permits static linking).

Download

There are two variants of the library, which are no longer completely synchronised:

SVN: http://svn.freepascal.org/svn/fpcprojects/lnet

You can contact the author directly by email or go to #lnet channel on freenode.

Usage

Drop a TLTCPComponent or TLUDPComponent on a form. Assign OnAccept, OnError, OnReceive, OnConnect and OnDisconnect event handlers. Note that this is optional but in most cases required for functionality.

Client connection is initialized with the Connect call. Arguments are IP address/hostname and port respectivly. Non-blocking connect is used, this means that you DON'T know that you're connected until OnConnect event is fired.

Server connection is initialized with the Listen* call. Argument is port.

Light bulb  Note: address is a string representation of IP eg: '127.0.0.1' or a hostname like 'localhost'.

Sending data to the other side is accomplished with the Send/SendMessage method.

Events of TLNetComponent

  • OnError - this event is fired whenever a connection error occurs. If no handler is assigned an excepion with "msg" is raised. Arguments are: msg - contains string and numerical representation of error message formatted in native encoding or UTF8 (depending on ForceUTF8 property). aSocket is the socket at which the error occured, nil means that the error is not a socket specific one.
  • OnConnect - This event is fired when the client succesfuly connects. aSocket is the socket which connected. It should serve as the "start" point for clients.
  • OnAccept - this event is fired whenever a connection is accepted on a server. If no handler is assigned nothing is done. aSocket contains the socket which accepted the connection.
  • OnDisconnect - this event is fired whenever a connection is lost. If no handler is assigned nothing is done. aSocket contains the socket which got disconnected.
  • OnReceive - This event is fired whenever new data is ready to be received. If no handler is assigned nothing is done, but a system buffer fill may happen which will in turn fire an OnError event. aSocket is the socket at which the data got received. Data is read by Get/GetMessage method.
  • OnCanSend - This event is fired whenever new data can be sent again on a socket, after a call to send function failed, returning 0. It can be used to automate sending of big chunks. aSocket is socket on which send can be called.

Documentation

Documentation of lNet is partially done. You can also use Jesus' diagrams of classes and units as basic reference.

Documentation of eventer and TCP/UDP protocols: http://members.chello.sk/ales/docs

Overview diagrams can be found here: http://members.chello.sk/ales/docs/diagrams/overview.html
Pictures:
New class diagram
All classes
lNet units
lNet units 2

Docs Mirror and Ongoing Notes: http://z505.com/cgi-bin/powtils/docs/1.6/idx.cgi?file=lnetlufdoc

Installation

LNet 0.5+:

  • In the lazarus/components directory, unzip the files from lnet-<version>.zip file. The lnet-<version> folder will be created.
  • Open Lazarus
  • Open the package lnet-<version>/lazaruspackage/lnetvisual.lpk with Package/Open package file (.lpk)
  • Click on Use/Install and answer 'Yes' when you are asked about Lazarus rebuilding. A new tab named 'lNet' will be created in the components palette.
Light bulb  Note: users who don't want to depend on LCL but use LNet in Lazarus (non-visually), can just compile lnetbase.lpk, which adds all the base units to path.

LNet 0.4:

  • In the lazarus/components directory, unzip the files from lnet-<version>.zip file. The lnet-<version> folder will be created.
  • Open Lazarus
  • Open the package lnet-<version>/lazaruspackage/lnetpackage.lpk with Package/Open package file (.lpk)
  • Click on Compile
  • Open the package lnet-<version>/lazaruspackage/ide/lnetidepackage.lpk with Package/Open package file (.lpk)
  • Click on Use/Install and answer 'Yes' when you are asked about Lazarus rebuilding. A new tab named 'lNet' will be created in the components palette.
Light bulb  Note: older lNet is extraced to "lnetpackage" dir. Since 0.4.0 the "visual" and "non visual" packages are in one distribution file.

Package contents

The package consists of base lNet units library, lTelnet for telnet protocol, lFTP for ftp protocol and lNetComponents libraries for providing visual and non-visual components for networking. As of 0.4.0 lHTTP and lSMTP components have been added. Since 0.5.1 there's a MIME support as part of the library mainly for creation of multipart messages for SMTP. Since 0.6.0 lNet supports SSL in a modular way, and SMTP protocol has been extended to full support of SSL/TLS (including runtime STARTTLS negotiation). HTTPS client side is supported too.

Testing

The non-visual console components were tested on Win32, Win64, Linux_x86_32, Linux_x86_64, Linux_PPC, Linux_PPC_64, Linux_ARM* (2.1.4+) and FreeBSD_x86_32. The visual (Lazarus packages) components were tested in Win32, Win64, ARM/WinCE, Linux_x86_32, Linux_x86_64 and FreeBSD_x86_32. (gtk1 and gtk2 on unix platforms)

History

  • March 2011: A new version of lNet was just released. 0.6.5 completes SSL and IPv6 support including server-side and per-socket (for SSL) setting. SSL and IPv6 bugs were fixed as well as some remaining disconnect problems related to server bind errors and lingering sockets. DecodeURL bug introduced in 0.6.4 was also fixed.
  • May 2010: A new version of lNet was just released. 0.6.4 adds Qt4 support inside Lazarus (lazarus latest trunk needed, 0.9.30 should be 1st stable with it). There were also numerous fixes (http URL parsing, FTP problems) and one major bug fixed (WinCE compilation with FPC 2.4.0+). Grab it at SVN, packages will be uploaded ASAP.
  • February 2010: Well there’s a skip in dates. Anyways version 0.6.3 of lNet has been released, you can find it in the downloads section. There’s been various bugfixes and file renames to avoid FPC conflicts. I didn’t find the time to do the QT4 port as I wanted but it’s in the works now. Some SSL fixes were made as well.
  • May 2008: Where to begin? This is a HUGE critical bugfix release. There was about 5 big bugs fixed in SSL section, one logical oversight in Session support. OpenSSL unit was added so WinCE compiles again and SMTP and FTP got bugs fixed in regards to possible desynchronization. I'd urge everyone who uses 0.6.x to update ASAP, but some bugs are also from 0.5.x (specifically the SMTP and FTP event deadlock problem).
  • May 2008: It seems that due to an oversight in what's packaged with FPC and for which platform, lNet 0.6.x doesn't currently compile on WinCE due to missing OpenSSL unit. The unit is in fpc 2.2.0, but is not compiled for that platform yet (it is in 2.2.1+). I will add the unit to lNet and release 0.6.2 shortly, but until then, WinCE users can work around this by copying this file into their lnetdir/lib directory. (same will be done in 0.6.2 so don't worry)
  • April 2008: 0.6.1 has been released today. This release fixes an ugly SSL logical bug in regards to the mandatory requirements of Certificate Authority List file and Keyfile proprties of SSLSession. They are no longer needed for normal SSL to work. A minor change in HTTP and handling of SSLSession are also present.

Stability

  • Base lNet TCP/UDP - stable
  • Telnet Client - stable*
  • FTP Client - stable*
  • SMTP Client - stable
  • HTTP Client - stable
  • HTTP Server - experimental
  • MIME streams - stable
  • SSL support (client-side) - stable
  • SSL support (server-side) - stable (0.6.5+)
  • IPv6 support - stable (0.6.5+)

* FTP and Telnet still need some additional features like authentication methods.

On Linux, since you start using LNet, GDB can crash randomly (upon compilations) with diverse kind of reports. Setting debugger to Automatic in both lnetbase and lnetvisual package's options fixes the issue.

Roadmap

Items that are struck through have been completed in the indicated version:

  • Stress testing [always]
  • Addition of Telnet and FTP clients (experimental level) [0.3] (done)
  • Cementing of TCP/UDP API [0.3] (done)
  • Addition of ICMP Ping/Traceroute protocol [na] (cancelled due to various reasons*)
  • Addition of SMTP, HTTP components [0.4] (done)
  • Stabilization of Telnet and FTP clients [0.5] (done)
  • Addition of MIME streams [0.5.1] (done)
  • Addition of Telnet and FTP servers (experimental level) [???]
  • Addition of SSL [0.6+] (done)
  • Addition of Carbon and/or Cocoa widget set support [0.7+]
  • Addition of Qt4 widget set support [0.6.4+] (done)
  • Cleanup of SSL/HTTP (so pure HTTP doesn't depend on TLSSLSocket) [0.6.x?]

* PING requires raw sockets which are only accessible to root on unix/linux platforms. It was decided that lNet won't support this, users who need PING should use the ping and ping6 programs via TProcess.

Requirements

LNet 0.6+:

  • Lazarus 0.9.24+ and FPC 2.2.0+
  • Status: Beta
  • Issues: Completely tested on Windows (WinXP), Linux (Ubuntu 7.10). FastCGI considered broken for now.

LNet 0.5:

  • Lazarus 0.9.22+ and FPC 2.0.4+
  • Status: Beta
  • Issues: Completely tested on Windows (WinXP), Linux (Ubuntu 6.10) and FreeBSD 5.5. FastCGI considered broken for now. WinCE requires Lazarus 0.9.23+ to compile!

LNet 0.4:

  • Lazarus 0.9.18+ and FPC 2.0.4+
  • Status: Beta
  • Issues: Completely tested on Windows (WinXP), Linux (Ubuntu 6.06LTS) and FreeBSD 6.1. HTTP server has issues under high load with fastcgi usage. FastCGI works only in Linux for now.

Ubuntu special notice

Some "missing files" are, in fact, in the "/net" subfolder and are not found by the fpc compiler. Simply copy missing files from the subfolder (lnet.pas, tomwinsock.pas, lfunc.inc...) "/usr/lib/lazarus/components/lnetpackage/lnet" in the "/usr/lib/lazarus/components/lnetpackage" folder (adjust paths as necessary). Then complete the setup by following the installation procedure. (by Steph12358)

API changes

0.1 to 0.2

  • There have been some API changes from 0.1 to 0.2. These were required and should improve the usability of packages. I know API changes are always a PITA but I'll try to keep them minimal from now on. Version 0.3 will be the first beta from which API will remain unchanged (only adding new stuff will be possible).
  • OnRecieve() changed to OnReceive()
  • Accept() changed to Listen()
  • All events' arguments changed. SocketNumber (int) got changed into aSocket(TLSocket) because of logical and speed reasons

0.2 to 0.3

  • Added OnCanSend and OnConnect. Connect is now non-blocking.
  • Removed buffersize and maxmsgs. Buffersize is no longer required because no internal buffer is used.

0.3 to 0.4

  • Lots of additions. Only "breakage" is that TLSocket.Port got changed into TLSocket.LocalPort and TLSocket.PeerPort for consistency reasons.

0.4 to 0.5

  • We did some API cleanup which resulted in API breakage.
  • All "connection" classes now descend from TLComponent
  • TLSocket now has a .Creator which is a TLComponent property specifying the creator (eg: TLTcp), so you can see now which socket in an event belongs to which connection.
  • Added "Connect()" and "Listen()" parameterless calls to all connections. This is mostly to enable Lazarus visual style, so people can use .Host and .Port properties and repeatedly just call ".Connect()" for example.
  • Added "StatusSet" set to SMTP and FTP components. This enables you to monitor specific FTP or SMTP actions and their results with events OnSuccess and OnFailure. You set the events to be watched in the set, and get results in one of the callbacks.
  • Changed ALL callbacks which didn't use TLSocket as sender to use it. This means all FTP, SMTP and HTTP events which had "Sender: TL<HigherType>" were reverted to basic Socket style callbacks!

0.5.4- to 0.5.5+

  • Some minor API changes were made which shouldn't break anything but I list them to be on the safe side.
  • .Timeout property on eventers and connections was set to Integer (from DWord) to support -1 as "block until an event happens"

0.5 to 0.6

  • No changes in public API, only additions.

Note for 0.4.0: In version 0.4.0, I forgot to move lHTTPSettings unit from lib to the http example. It was NOT supposed to be a part of the library, just the example. DON'T use this, it's not a "library", it's a part of the example (http server will get it's own project later)