The protosocket library provides an interface to the uIP stack that is similar to the traditional BSD socket interface.

Unlike programs written for the ordinary uIP event-driven interface, programs written with the protosocket library are executed in a sequential fashion and does not have to be implemented as explicit state machines.

Protosockets only work with TCP connections.

The protosocket library uses Pt protothreads to provide sequential control flow. This makes the protosockets lightweight in terms of memory, but also means that protosockets inherits the functional limitations of protothreads. Each protosocket lives only within a single function block. Automatic variables (stack variables) are not necessarily retained across a protosocket library function call.

Note: Because the protosocket library uses protothreads, local variables will not always be saved across a call to a protosocket library function. It is therefore advised that local variables are used with extreme care.

The protosocket library provides functions for sending data without having to deal with retransmissions and acknowledgements, as well as functions for reading data without having to deal with data being split across more than one TCP segment.

Because each protosocket runs as a protothread, the protosocket has to be started with a call to PSOCK_BEGIN() at the start of the function in which the protosocket is used. Similarly, the protosocket protothread can be terminated by a call to PSOCK_EXIT().

Data Structures
struct	psock
	The representation of a protosocket. More...

struct	psock_buf

Files
file	psock.h
	Protosocket library header file.

Macros
#define	PSOCK_BEGIN(psock)
	Start the protosocket protothread in a function. More...

#define	PSOCK_CLOSE(psock)
	Close a protosocket. More...

#define	PSOCK_CLOSE_EXIT(psock)
	Close a protosocket and exit the protosocket's protothread. More...

#define	PSOCK_DATALEN(psock)
	The length of the data that was previously read. More...

#define	PSOCK_END(psock)
	Declare the end of a protosocket's protothread. More...

#define	PSOCK_EXIT(psock)
	Exit the protosocket's protothread. More...

#define	PSOCK_GENERATOR_SEND(psock, generator, arg)
	Generate data with a function and send it. More...

#define	PSOCK_INIT(psock, buffer, buffersize)
	Initialize a protosocket. More...

#define	PSOCK_NEWDATA(psock)
	Check if new data has arrived on a protosocket. More...

#define	PSOCK_READBUF(psock)
	Read data until the buffer is full. More...

#define	PSOCK_READBUF_LEN(psock, len)
	Read data until at least len bytes have been read. More...

#define	PSOCK_READTO(psock, c)
	Read data up to a specified character. More...

#define	PSOCK_SEND(psock, data, datalen)
	Send data. More...

#define	PSOCK_SEND_STR(psock, str)
	Send a null-terminated string. More...

#define	PSOCK_WAIT_THREAD(psock, condition) PT_WAIT_THREAD(&((psock)->pt), (condition))

#define	PSOCK_WAIT_UNTIL(psock, condition)
	Wait until a condition is true. More...

Functions
uint16_t	psock_datalen (struct psock *psock)

void	psock_init (struct psock psock, uint8_t buffer, unsigned int buffersize)

char	psock_newdata (struct psock *s)

	PT_THREAD (psock_send(struct psock psock, const uint8_t buf, unsigned int len))

	PT_THREAD (psock_generator_send(struct psock psock, unsigned short(f)(void ), void arg))

	PT_THREAD (psock_readbuf_len(struct psock *psock, uint16_t len))

	PT_THREAD (psock_readto(struct psock *psock, unsigned char c))

#define PSOCK_BEGIN ( psock )

Start the protosocket protothread in a function.

This macro starts the protothread associated with the protosocket and must come before other protosocket calls in the function it is used.

Parameters

psock (struct psock *) A pointer to the protosocket to be started.

#define PSOCK_CLOSE ( psock )

Close a protosocket.

This macro closes a protosocket and can only be called from within the protothread in which the protosocket lives.

Parameters

psock (struct psock *) A pointer to the protosocket that is to be closed.

#define PSOCK_CLOSE_EXIT ( psock )

Close a protosocket and exit the protosocket's protothread.

This macro closes a protosocket and exits the protosocket's protothread.

Parameters

psock (struct psock *) A pointer to the protosocket.

Referenced by if().

#define PSOCK_DATALEN ( psock )

The length of the data that was previously read.

This macro returns the length of the data that was previously read using PSOCK_READTO() or PSOCK_READ().

Parameters

psock (struct psock *) A pointer to the protosocket holding the data.

Referenced by while().

#define PSOCK_END ( psock )

Declare the end of a protosocket's protothread.

This macro is used for declaring that the protosocket's protothread ends. It must always be used together with a matching PSOCK_BEGIN() macro.

Parameters

psock (struct psock *) A pointer to the protosocket.

#define PSOCK_EXIT ( psock )

Exit the protosocket's protothread.

This macro terminates the protothread of the protosocket and should almost always be used in conjunction with PSOCK_CLOSE().

See Also: PSOCK_CLOSE_EXIT()

Parameters

psock (struct psock *) A pointer to the protosocket.

#define PSOCK_GENERATOR_SEND	(	psock,
		generator,
		arg
	)

Generate data with a function and send it.

Parameters

psock Pointer to the protosocket.

generator Pointer to the generator function

arg

Argument to the generator function

        This function generates data and sends it over the
        protosocket. This can be used to dynamically generate
        data for a transmission, instead of generating the data
        in a buffer beforehand. This function reduces the need for
        buffer memory. The generator function is implemented by
        the application, and a pointer to the function is given
        as an argument with the call to PSOCK_GENERATOR_SEND().

        The generator function should place the generated data
        directly in the uip_appdata buffer, and return the
        length of the generated data. The generator function is
        called by the protosocket layer when the data first is
        sent, and once for every retransmission that is needed.

Referenced by for().

#define PSOCK_INIT	(	psock,
		buffer,
		buffersize
	)

Initialize a protosocket.

This macro initializes a protosocket and must be called before the protosocket is used. The initialization also specifies the input buffer for the protosocket.

Parameters

psock	(struct psock *) A pointer to the protosocket to be initialized
buffer	(uint8_t *) A pointer to the input buffer for the protosocket.
buffersize	(unsigned int) The size of the input buffer.

Referenced by httpd_appcall().

#define PSOCK_NEWDATA ( psock )

Check if new data has arrived on a protosocket.

This macro is used in conjunction with the PSOCK_WAIT_UNTIL() macro to check if data has arrived on a protosocket.

Parameters

psock (struct psock *) A pointer to the protosocket.

#define PSOCK_READBUF ( psock )

Read data until the buffer is full.

This macro will block waiting for data and read the data into the input buffer specified with the call to PSOCK_INIT(). Data is read until the buffer is full..

Parameters

psock (struct psock *) A pointer to the protosocket from which data should be read.

#define PSOCK_READBUF_LEN	(	psock,
		len
	)

Read data until at least len bytes have been read.

This macro will block waiting for data and read the data into the input buffer specified with the call to PSOCK_INIT(). Data is read until the buffer is full or len bytes have been read.

Parameters

psock	(struct psock *) A pointer to the protosocket from which data should be read.
len	(uint16_t) The minimum number of bytes to read.

#define PSOCK_READTO	(	psock,
		c
	)

Read data up to a specified character.

This macro will block waiting for data and read the data into the input buffer specified with the call to PSOCK_INIT(). Data is only read until the specified character appears in the data stream.

Parameters

psock	(struct psock *) A pointer to the protosocket from which data should be read.
c	(char) The character at which to stop reading.

Referenced by while().

#define PSOCK_SEND	(	psock,
		data,
		datalen
	)

Send data.

This macro sends data over a protosocket. The protosocket protothread blocks until all data has been sent and is known to have been received by the remote end of the TCP connection.

Parameters

psock	(struct psock *) A pointer to the protosocket over which data is to be sent.
data	(uint8_t *) A pointer to the data that is to be sent.
datalen	(unsigned int) The length of the data that is to be sent.

#define PSOCK_SEND_STR	(	psock,
		str
	)

Send a null-terminated string.

Parameters

psock	Pointer to the protosocket.
str	The string to be sent. This function sends a null-terminated string over the protosocket.

Referenced by if().

#define PSOCK_WAIT_THREAD	(	psock,
		condition
	)	PT_WAIT_THREAD(&((psock)->pt), (condition))

#define PSOCK_WAIT_UNTIL	(	psock,
		condition
	)

Wait until a condition is true.

This macro blocks the protothread until the specified condition is true. The macro PSOCK_NEWDATA() can be used to check if new data arrives when the protosocket is waiting.

Typically, this macro is used as follows:

PT_THREAD(thread(struct psock *s, struct timer *t))
{
  PSOCK_BEGIN(s);
  PSOCK_WAIT_UNTIL(s, PSOCK_NEWDATA(s) || timer_expired(t));
  
  if(PSOCK_NEWDATA(s)) {
    PSOCK_READTO(s, '\n');
  } else {
    handle_timed_out(s);
  }
  
  PSOCK_END(s);
}

Parameters

psock	(struct psock *) A pointer to the protosocket.
condition	The condition to wait for.

uint16_t psock_datalen ( struct psock * psock )

References buf, bufsize, and psock_buf::left.

void psock_init	(	struct psock *	psock,
		uint8_t *	buffer,
		unsigned int	buffersize
	)

char psock_newdata ( struct psock * s )

References readlen, state, STATE_BLOCKED_NEWDATA, STATE_READ, and uip_newdata.

PT_THREAD ( psock_send(struct psock *psock, const uint8_t *buf, unsigned int len) )

PT_THREAD ( psock_generator_send(struct psock *psock, unsigned short(*f)(void *), void *arg) )

PT_THREAD ( psock_readbuf_len(struct psock *psock, uint16_t len) )

PT_THREAD ( psock_readto(struct psock *psock, unsigned char c) )

Microchip® Advanced Software Framework

Data Structures

Files

Macros

Functions