conSock: what changed
Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 2 | - | ||
| 3 | - | ||
| 4 | - | ||
| 5 | - | ||
| 6 | - | ||
| 7 | - | ||
| 8 | - | ||
| 9 | - | ||
| 10 | 1 | ## About | |
| 11 | 2 | ||
| 12 | - | ||
| 3 | + | conSock is a Lazarus library that implements TCP/IP connections, in Client-Server mode, using sockets. It is based on [[Synapse]]. Tested only in Windows. | |
| 13 | 4 | ||
| 14 | - | ||
| 5 | + | Author: Tito Hinostroza | |
| 15 | 6 | ||
| 16 | - | ||
| 7 | + | License: GPL v3 | |
| 17 | 8 | ||
| 18 | 9 | ## Usage | |
| 19 | 10 | ||
| 20 | - | ||
| 11 | + | Using the library is easy because it presents objects that communicate using events. At the low level the objects are implemented using blocking sockets and threads. | |
| 21 | 12 | ||
| 22 | - | ||
| 13 | + | The connection model is similar to a Client-Server architecture, with the following rules: | |
| 23 | 14 | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 27 | - | ||
| 28 | - | ||
| 15 | + | - To implement a communication, there must be one Client and one Server part. | |
| 16 | + | - Client part must be set with the IP address of the Server part. Server doesn't need to be set. | |
| 17 | + | - Server part can connect only to one client. If there are several clients connecting to the same server, only the first will be accepted. | |
| 18 | + | - Once the connection is established, only client can start the communication. The server can respond only to a client request. | |
| 19 | + | - All communications are implemented using the same Frame structure. | |
| 29 | 20 | ||
| 30 | - | ||
| 21 | + | Default IP for Client is 127.0.0.1. Default port for Client and Server is 80. | |
| 31 | 22 | ||
| 32 | 23 | ### Frame structure | |
| 33 | 24 | ||
| 34 | - | ||
| 25 | + | Library implements a Frame including: | |
| 35 | 26 | ||
| 36 | - | ||
| 37 | - | ||
| 27 | + | - Header part: 9 bytes size | |
| 28 | + | - Data part: Optional. Can be as big as 16777215 bytes | |
| 38 | 29 | ||
| 39 | - | ||
| 30 | + | Header part is small (fixed size 9 bytes) and has the following structure: | |
| 40 | 31 | ||
| 41 | - | ||
| 42 | - | ||
| 43 | - | ||
| 44 | - | ||
| 45 | - | ||
| 32 | + | - 1 byte: Header ID. Header ID is always the hexadecimal value \$0F, and is a way to identify the start of a frame. | |
| 33 | + | - 3 bytes: Data part size. The "Data part size" indicates the size of the "Data part". | |
| 34 | + | - 1 byte: Command. User can send any command in the frame field "Command". But the values \$03 and \$83 are reserved to internal dialog of the protocol. | |
| 35 | + | - 2 bytes: X parameter. Parameters X and Y can be used to send additional information for a command. | |
| 36 | + | - 2 bytes: Y parameter. | |
| 46 | 37 | ||
| 47 | 38 | ### Units | |
| 48 | 39 | ||
| 49 | - | ||
| 40 | + | The library contains 3 units: | |
| 50 | 41 | ||
| 51 | - | ||
| 52 | - | ||
| 53 | - | ||
| 42 | + | - conSockFrames.pas - Defines the protocol and the routines to code/decode the Frame packet. | |
| 43 | + | - conSockClient.pas - Defines the base client object TConSockClient. | |
| 44 | + | - conSockServer.pas - Defines the base server object TConSockServer. | |
| 54 | 45 | ||
| 55 | - | ||
| 46 | + | To implement a basic connection, it's needed to create a client and server object. | |
| 56 | 47 | ||
| 57 | - | ||
| 58 | - | ||
| 48 | + | - Client Part - Modelled with the object TConSockClient. | |
| 49 | + | - Server Part - Modelled with the object TConSockServer. | |
| 59 | 50 | ||
| 60 | 51 | ### Example | |
| 61 | 52 | ||
| 62 | - | ||
| 63 | - | ||
| 64 | - | ||
| 65 | - | ||
| 66 | - | ||
| 67 | - | ||
| 68 | - | ||
| 69 | - | ||
| 70 | - | ||
| 71 | - | ||
| 72 | - | ||
| 53 | + | To implement a simple connection, it's needed to create a client part and a server part: | |
| 54 | + | ||
| 55 | + | ``` pascal | |
| 56 | + | //Set client | |
| 57 | + | client := TConSockClient.Create('127.0.0.1'); | |
| 58 | + | client.OnFrameReady := @clientFrameReady; | |
| 59 | + | client.Connect; | |
| 60 | + | ||
| 61 | + | //Set server | |
| 62 | + | Server := TConSockServer.Create; | |
| 63 | + | Server.OnFrameReady := @ServerFrameReady; | |
| 64 | + | Server.Connect; | |
| 73 | 65 | ``` | |
| 74 | 66 | ||
| 75 | - | ||
| 67 | + | Event OnFrameReady is triggered every time a Frame is received. | |
| 76 | 68 | ||
| 77 | - | ||
| 69 | + | The state of the connection can be read in the field client.state and in server.State. This state can be: | |
| 78 | 70 | ||
| 79 | - | ||
| 80 | - | ||
| 81 | - | ||
| 82 | - | ||
| 71 | + | - cecCONNECTING | |
| 72 | + | - cecCONNECTED | |
| 73 | + | - cecSTOPPED | |
| 74 | + | - cecDEAD | |
| 83 | 75 | ||
| 84 | - | ||
| 85 | - | ||
| 86 | - | ||
| 76 | + | To send data from the client, we can use the following instruction: | |
| 77 | + | ||
| 78 | + | ``` pascal | |
| 79 | + | client.SendCommand($FF, 0, 0, sometext); | |
| 87 | 80 | ``` | |
| 88 | 81 | ||
| 89 | - | ||
| 82 | + | Where \$FF represents some command, and "sometext" represents the data part of the command. We can use different commands number, except the values \$03 and \$83 that are reserved for the library. | |
| 90 | 83 | ||
| 91 | - | ||
| 84 | + | For a complete code, check the sample projects. | |
| 92 | 85 | ||
| 93 | 86 | ## Download | |
| 94 | 87 | ||
| 95 | 88 | GitHub: <https://github.com/t-edson/conSock> | |
| 96 | 89 | ||
| 97 | 90 | --- | |
| 98 | - | ||
| 91 | + | *From the Free Pascal wiki, page "conSock", as it stood on 2020-10-07 after a change by Bart, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* | |
| 92 | + | Category: Lazarus | |
| 93 | + | Category: Networking |