# Sockets
[Core]

The Sockets system provides a simple interface for creating, reading and writing over both TCP and UDP. More...

## Defines
#define | IP_ADDRESS(a, b, c, d) ( ( (int)a << 24 ) + ( (int)b << 16 ) + ( (int)c << 8 ) + (int)d )
| Generate an address appropriate for Socket functions from 4 integers.
## Functions
void * | Socket (int address, int port)
| Create a new TCP socket connected to the address and port specified.
int | SocketBytesAvailable (void *socket)
| Get the number of bytes available in a TCP socket.
int | SocketRead (void *socket, char *data, int length)
| Read from a TCP socket.
int | SocketReadLine (void *socket, char *data, int length)
| Read a line from a TCP socket terminated by CR LF (0x0D 0x0A).
int | SocketWrite (void *socket, char *data, int length)
| Write to a TCP socket.
void | SocketClose (void *socket)
| Close an existing TCP socket.
void * | ServerSocket (int port)
| Create a new TCP server socket and start listening for connections.
void * | ServerSocketAccept (void *serverSocket)
| Accept an incoming connection to a ServerSocket that you have created.
int | ServerSocketClose (void *serverSocket)
| Close a ServerSocket that you have created.
void * | DatagramSocket (int port)
| Create a socket to read and write UDP packets.
int | DatagramSocketSend (void *datagramSocket, int address, int port, void *data, int length)
| Send a UDP packet to a specified address.
int | DatagramSocketReceive (void *datagramSocket, int incomingPort, int *address, int *port, void *data, int length)
| Receive a UDP packet.
void | DatagramSocketClose (void *socket)
| Close a DatagramSocket().

## Detailed Description

The Sockets system provides a simple interface for creating, reading and writing over both TCP and UDP.

This subsystem is a light wrapper around LwIP, the open source TCP/IP stack used by the Make Controller Kit. There are 3 groups of socket functions:

- DatagramSocket - sockets for UDP communication
- Socket - sockets for TCP communication
- ServerSocket - sockets for accepting incoming TCP client connections

## Define Documentation

#define IP_ADDRESS | ( | a,
|  | b,
|  | c,
|  | d |  | ) | ( ( (int)a << 24 ) + ( (int)b << 16 ) + ( (int)c << 8 ) + (int)d )

Generate an address appropriate for Socket functions from 4 integers.

Example

      void* sock = Socket( IP_ADDRESS( 192, 168, 0, 200 ), 80 );

Definition at line 36 of file network.h.

## Function Documentation

void* DatagramSocket | ( | int | port | ) |

Create a socket to read and write UDP packets.

Parameters:

  | port | An integer specifying the port to open.

Returns:
  a pointer to the socket created.

See also:
  DatagramSocketSend( ), DatagramSocketReceive( )

Example

        // create a new UDP socket on port 10101
        struct netconn* udpSocket = DatagramSocket( 10101 );
        // now read and write to it using DatagramSocketSend( ) and DatagramSocketReceive( )

Definition at line 432 of file network.c.

void DatagramSocketClose | ( | void * | socket | ) |

Close a DatagramSocket().

Parameters:

  | socket | A pointer to the DatagramSocket() to close.

See also:
  DatagramSocket( )

Example

        struct netconn* udpSocket = DatagramSocket( 10101 ); // create our socket
        // now close it
        DatagramSocketClose( udpSocket );

Definition at line 562 of file network.c.

int DatagramSocketReceive | ( | void * | datagramSocket,
|  | int | incomingPort,
|  | int * | address,
|  | int * | port,
|  | void * | data,
|  | int | length |
| ) |  |  |

Receive a UDP packet.

This function will block until a packet is received. The address and port of the sender are returned in the locations pointed to by the address and port parameters. If the incoming packet is larger than the specified size of the buffer, it will be truncated.

Parameters:

  | datagramSocket | A pointer to the DatagramSocket() you're using to read.
  | incomingPort | An integer specifying the port to listen on.
  | address | A pointer to the IP address that sent the packet.
  | port | A pointer to the port of the sender.
  | data | A pointer to the buffer to read into.
  | length | An integer specifying the number of bytes in the packet being read.

Returns:
  An integer corresponding to the number of bytes successfully read.

See also:
  DatagramSocket( )

Example

        struct netconn* udpSocket = DatagramSocket( 10101 ); // our socket
        int address, port;
        int sent = DatagramSocketReceive( udpSocket, &address, &port, myBuffer, myLength );

Definition at line 517 of file network.c.

int DatagramSocketSend | ( | void * | datagramSocket,
|  | int | address,
|  | int | port,
|  | void * | data,
|  | int | length |
| ) |  |  |

Send a UDP packet to a specified address.

Parameters:

  | datagramSocket | A pointer to the DatagramSocket() you're using to write.
  | address | An integer specifying the IP address to write to.
  | port | An integer specifying the port to write to.
  | data | A pointer to the packet to send.
  | length | An integer specifying the number of bytes in the packet being sent.

Returns:
  An integer corresponding to the number of bytes successfully written.

See also:
  DatagramSocket( )

Example

        struct netconn* udpSocket = DatagramSocket( 10101 ); // our socket
        int address = IP_ADDRESS( 192, 168, 0, 200 );
        int sent = DatagramSocketSend( udpSocket, address, 10101, myBuffer, myLength );

Definition at line 467 of file network.c.

void* ServerSocket | ( | int | port | ) |

Create a new TCP server socket and start listening for connections.

Parameters:

  | port | An integer specifying the port to listen on.

Returns:
  A pointer to the socket created.

See also:
  ServerSocketAccept( )

Example

        // create a socket and start listening on port 10101
        struct netconn* server = ServerSocket( 10101 );
        // ServerSocketAccept( ) will block until an incoming connection is made
        struct netconn* newConnection = ServerSocketAccept( server );
        // now grab the data from the new connection

Definition at line 364 of file network.c.

void* ServerSocketAccept | ( | void * | serverSocket | ) |

Accept an incoming connection to a ServerSocket that you have created.

This function will block until a new connection is waiting to be serviced. It returns a regular socket on which you can use SocketWrite(), SocketRead() and SocketClose().

Parameters:

  | serverSocket | a pointer to a ServerSocket that you created

Returns:
  a pointer to the new socket created to handle the connection

See also:
  ServerSocket(), SocketWrite(), SocketRead(), SocketClose()

Definition at line 388 of file network.c.

int ServerSocketClose | ( | void * | serverSocket | ) |

Close a ServerSocket that you have created.

Parameters:

  | serverSocket | A pointer to a ServerSocket.

Returns:
  0 if the process was successful.

See also:
  ServerSocket()

Example

        // we created a server socket at some point
        struct netconn* server = ServerSocket( 10101 );
        // now close it
        ServerSocketClose( server );

Definition at line 412 of file network.c.

void* Socket | ( | int | address,
|  | int | port |
| ) |  |  |

Create a new TCP socket connected to the address and port specified.

Parameters:

  | address | An integer specifying the IP address to connect to.
  | port | An integer specifying the port to connect on.

Returns:
  A pointer to the socket, if it was created successfully. NULL if unsuccessful.

See also:
  SocketRead(), SocketWrite(), SocketClose()

Example

        // use the IP_ADDRESS macro to format the address properly
        int addr = IP_ADDRESS( 192, 168, 0, 54 );
        // then create the socket, connecting on port 10101
        struct netconn* socket = Socket( addr, 10101 );

Definition at line 113 of file network.c.

int SocketBytesAvailable | ( | void * | socket | ) |

Get the number of bytes available in a TCP socket.

Handy before calling SocketRead() so you know how many to read.

Parameters:

  | socket | The socket.

Returns:
  The number of bytes available in that socket.

Example

      struct netconn* mysocket = Socket(IP_ADDRESS( 192, 168, 0, 54 ), 10101);
      // ... reading and writing ...
      int avail = Socket_BytesAvailable(mysocket);

Definition at line 154 of file network.c.

void SocketClose | ( | void * | socket | ) |

Close an existing TCP socket.

Anytime you get an error when trying to read or write, it's best to close the socket and reopen it to make sure that the connection is corrently configured.

Parameters:

  | socket | A pointer to the existing socket.

Returns:
  void

See also:
  Socket()

Example

        // we should already have created a socket 'sock' with Socket().
        struct netconn* sock = Socket( addr, 10101 );
        // now close it
        SocketClose( sock )

Definition at line 334 of file network.c.

int SocketRead | ( | void * | socket,
|  | char * | data,
|  | int | length |
| ) |  |  |

Read from a TCP socket.

Make sure you have an open socket before trying to read from it. This function will block until the requested number of bytes are read. See Socket_BytesAvailable() to get the number of bytes waiting to be read.

Parameters:

  | socket | A pointer to the existing socket.
  | data | A pointer to the buffer to read to.
  | length | An integer specifying the maximum length in bytes that can be read.

Returns:
  An integer: length of data read if successful, zero on failure.

See also:
  Socket(), SocketClose()

Example

        // we should already have created a socket sock with Socket().
        struct netconn* sock = Socket( addr, 10101 );
        int length_read = SocketRead( sock, data, length )
        // if 0 bytes were read, there was some sort of error
        if( length_read == 0 )
          SocketClose( sock );

Definition at line 186 of file network.c.

int SocketReadLine | ( | void * | socket,
|  | char * | data,
|  | int | length |
| ) |  |  |

Read a line from a TCP socket terminated by CR LF (0x0D 0x0A).

Make sure you have an open socket before trying to read from it.

Parameters:

  | socket | A pointer to the existing socket.
  | data | A pointer to the buffer to read to.
  | length | An integer specifying the maximum length in bytes to read.

Returns:
  An integer: length of data read if successful, zero on failure.

See also:
  Socket(), SocketRead(), SocketClose()

Definition at line 262 of file network.c.

int SocketWrite | ( | void * | socket,
|  | char * | data,
|  | int | length |
| ) |  |  |

Write to a TCP socket.

Not surprisingly, we need an existing socket before we can write to it.

Parameters:

  | socket | A pointer to the existing socket.
  | data | A pointer to the buffer to write from.
  | length | An integer specifying the length in bytes of how much data should be written.

Returns:
  An integer: 'length written' if successful, 0 on failure.

See also:
  Socket()

Example

        // we should already have created a socket with Socket()
        struct netconn* sock = Socket( addr, 10101 );
        int length_written = SocketWrite( sock, data, length )
        // if 0 bytes were written, there was some sort of error
        if( length_written == 0 )
          SocketClose( sock );

Definition at line 309 of file network.c.