## Socket

### Description

The Socket class allows you to use the low-level networking facilities provided by BSD or Windows sockets, for client-server applications. (See also the GetMail, SendMail and HTTPClient classes, which provide a higher-level interface for mail and HTTP protocols, and which are much easier to use.) It allows your APLX applications to exchange data with other processes, either on the local machine or over a network.

Usually, you will use Socket objects to allow APLX applications to communicate with non-APL processes. You can also use them to allow APLX applications to communicate with each other across a network.

For more details on using sockets, consult any of the standard documents on BSD or Windows socket programming.

### Creating and using a socket as a client

The steps you need to carry out at the client end of the connection are as follows:

1. Create a Socket object, as a top-level object.
2. If necessary, set the `family` and `protocol` properties to specify the type of socket you want.
3. Call the `Open` method to establish the connection with the server. This takes two arguments. The first is the network address of the server, as a character string; for example, this might be 'localhost' (your own machine), or '192.100.200.1' (an internet address) or 'www.microapl.co.uk' (an internet domain name). The second argument is the port number. Port numbers are usually associated with specific type of network protocol, for example port 80 is used for HTTP (web access). The `Open` method returns a status code indicating whether it succeeded: 0 = OK, 1 = Could not find host, 2 = Authentication error, 3 = Other error. If the connection was established successfully, you can now exchange data with the server.
4. To send data to the server, call the `Send` method. This takes a character vector argument. The data is sent exactly as it, without any character translation (i.e. the character vector is treated as a sequence of raw bytes). The return code is 0 for success, or 3 if an error occurs (see the description of the `status` property below).
5. To receive data from the server, call the `Receive` method. This takes no arguments. It returns a character vector, which is the data received (as an untranslated sequence of raw bytes). The APL task will block until the data has been received, or the time specified in the `timeout` property has elapsed. Note: If you do not want the task to be blocked waiting for data, use the `onReceive` event to ensure that `Receive` is called only when there is data already waiting.
6. To end the session, call the `Close` method. This takes no arguments.

### Creating and using a socket as a server

At the server end of a connection, things are usually a little more complex. This is because a server typically needs to be able to handle multiple client connections simultaneously, and must not get blocked communicating with one client when other clients are also trying to access the service. One way of handling this is to use multiple APLX tasks, with one task per client connection, plus one master task which waits for clients to connect. Another way is to use a single APLX task for everything, and use events to ensure that the task never gets blocked waiting for a response from a client.

The task which is waiting for clients to connect starts up first. It does the following:

1. Create a Socket object, as a top-level object.
2. Set the `port` property, to specify which port to listen to. If necessary, set the `family` and `protocol` properties to specify the type of socket you want.
3. Call the `Listen` method. This sets up the socket so that it is associated with the port.
4. You can now do one of two things. If the server task does not need to do anything until a client tries to connect, you can simply call the `Accept` method. The task will block, waiting for the next connection (or until the time specified by the timeout property has elapsed). Alternatively, you can set up an `onConnectRequest` callback, and call the `Accept` method only when a client tries to establish a connection.
5. If an request from a client to establish a new connection is successful, the `Accept` method returns a non-zero positive integer. This is the internal handle for a new underlying operating-system socket, which can be used to exchange data with the client. The `Accept` method will return 0 if it timed out, or ¯1 if it could not establish the connection.
6. The server now needs to create a new Socket object (as a top-level object), which will be used to exchange data with the client which has just connected. The internal handle returned by the `Accept` method should be written to the `handle` property of the new Socket object. It will often be convenient to create this new socket in a new APLX task (see the description of the APL object), although this is not essential. Data exchange takes place using the `Send` and `Receive` methods, as already described for the client end of the connection. When the connection is no longer needed, it should be closed using the `Close` method, and deleted.
7. Meanwhile, the server loops back to step 4 and calls `Accept` again to wait for a new client connection, or waits for an `onConnectRequest` event.

### Key properties of the Socket object

`family`: An integer scalar which specifies the address family of the socket. The default is 2, AF_INET, the address family used for the internet. It should be specified before calling the `Open` or `Listen` methods.

`type`: An integer scalar which specifies the socket type. It defaults to 1, SOCK_STREAM. It should be specified before calling the `Open` or `Listen` methods.

`protocol`: An integer scalar which specifies the protocol. It defaults to 0, the default for the address family.

`port`: An integer scalar which specifes the port number.

`timeout`: An integer scalar which sets the timeout (in milliseconds) before the `Accept` or `Receive` methods will return if no connection request or data is received. A value of ¯1 means 'wait for ever'. A value of 0 means 'return immediately'.

`status`: Read-only Returns the connection status as a two-element vector. The first element is 1 if the socket is connected, else 0. The second element is the latest error number from the underlying operating-system socket.

`handle`: An integer scalar, which is the handle of the underlying operating-system handle. You can use this, in conjunction with ŒNA, to access socket functions not supported by the Socket object. You also need to write the result of the `Accept` method to this value at the server end, when you have created a new socket to accept an incoming client connection.

### Key methods of the Socket object

`Open`: Open a new connection. (This method should be called from the client end of the connection only.) It takes two arguments. The first is the address of the server (usually an internet domain name or address, or `'localhost'` for your own machine). The second is the port number to connect on. The result is a status code indicating whether the connection succeeded: 0 = OK, 1 = Could not find host, 2 = Authentication error, 3 = Other error. (More details of any error are available from the `status` property).

`Listen`: Establish the socket as a server listener. This method takes no arguments. (It should be called on the server end of the connection only.). It returns the same error code as `Open`.

`Accept`: Wait for a client to try to connect. This method takes no arguments. (It should be called on the server end of the connection only.). It causes the task to block until a connection request is made, or the `timeout` value is reached. It returns the `handle` to use for the client connection, or 0 if it timed out or ¯1 if it could not establish the connection.

`Receive`: Receive some data from the socket. This method takes no arguments. It causes the task to block until data is available, or the `timeout` value is reached. It returns a character vector which is the data received from the socket, as a raw sequence of bytes with no character translation. It returns an empty vector if it times out or an error occurs.

`Send`: Send some data to the socket. This method takes as an argument a character vector, which is the raw data to send to the other end of the connection. It returns 0 on success, else 3 if an error occurred.

`Close`: Disconnect and close the socket. This method takes no arguments. You always ensure the connection is closed cleanly by calling this method when the session is complete.

### Callbacks of the Socket object

`onConnectRequest`: This event occurs on the server end, when you have called `Listen` and a client tries to connect. It indicates that you should now call the `Accept` method to accept the connection.

`onReceive`: This event occurs both on clients and servers. It indicates that the other end has sent some data, which you can now read using the `Receive` method.

`onDisconnect`: This event occurs both on clients and servers. It indicates that the other end has closed the connection. You should now call `Close`, and delete the socket.

### Example

         ’DEMO_Socket;x;count;handle;cmd;errcode;ServerSock;Client1;Client2;SendSock
    [1]   © Show how to use the Socket object. For this demo, we set up a
    [2]   © Server and two client APL tasks, all on the local machine
    [3]   © using port 10000 (which hopefully won't clash with anything)
    [4]   Client1„'Œ' ŒNEW 'APL' ª Client1.wssize„100000 ª Client1.where„0 0 10 20
    [5]   Client2„'Œ' ŒNEW 'APL' ª Client2.wssize„100000 ª Client2.where„0 35 10 20
    [6]   Client1.Open
    [7]   Client2.Open
    [8]   ©
    [9]   © Create sockets in each client APL task
    [10]  Client1.Execute "MySock„'Œ' ŒNEW 'Socket'"
    [11]  Client2.Execute "MySock„'Œ' ŒNEW 'Socket'"
    [12]  ©
    [13]  © Create a socket for the server, in our main task
    [14]  ServerSock„'Œ' ŒNEW 'Socket'
    [15]  ServerSock.port„10000
    [16]  errcode„ServerSock.Listen
    [17]  :If errcode¬0
    [18]    © Oops, something went wrong
    [19]    'An error occurred in Listen, error code ',•¯1†ServerSock.status
    [20]    :Return
    [21]  :EndIf
    [22]  ©
    [23]  © After a few seconds, get the clients to try to connect, and await data
    [24]  x„ŒDL 3
    [25]  cmd„"x„MySock.Open 'localhost' 10000 ª 'Server sent: ',MySock.Receive"
    [26]  Client1.Execute("x„ŒDL 3 ª 'Connecting..' ª ",cmd)
    [27]  Client2.Execute("x„ŒDL 6 ª 'Connecting..' ª ",cmd)
    [28]  ©
    [29]  © Meanwhile, loop round accepting connections
    [30]  count„0
    [31]  'Waiting for clients to connect...' ª ŒCC ' '
    [32]  :Repeat
    [33]    handle„ServerSock.Accept
    [34]    :If handle>0
    [35]      © A client is trying to connect
    [36]      © Establish new socket to talk to the client.
    [37]      © We'll just transfer one packet, then close the connection
    [38]      'Got connection request.' ª ŒCC ' '
    [39]      count„count+1
    [40]      SendSock„'Œ' ŒNEW 'Socket'
    [41]      SendSock.handle„handle
    [42]      errcode„SendSock.Send('Hello, client task ',•count)
    [43]      SendSock.Close
    [44]      SendSock.Delete
    [45]    :ElseIf handle=¯1
    [46]      © Oops, something went wrong
    [47]      'An error occurred in Accept, error code ',•¯1†ServerSock.status
    [48]      :Leave
    [49]    :EndIf
    [50]  :Until count=2
    [51]  ©
    [52]  © Wait, then kill the child tasks (this will also delete their sockets)
    [53]  x„ŒDL 4
    [54]  Client1.Close ª Client2.Close
    [55]  ©
    [56]  © Clean up this end as well
    [57]  ServerSock.Close
         ’

### Properties

children class data events family handle methods name opened port properties protocol self status tie timeout type

### Methods

Accept Close Create Delete Listen New Open Receive Send Set Trigger

### Callbacks

onClose onConnectRequest onDestroy onDisconnect onOpen onReceive onSend

Topic: APLX Help : System Classes : List of Classes : Socket

[ Previous | Next | Contents | Index ]