API

Configuration Defines

The following defines can be set by adding the file xtcp_client_conf.h into your application and setting the defines within that file.

XTCP_CLIENT_BUF_SIZE

The buffer size used for incoming packets. This has a maximum value of 1472 which can handle any incoming packet. If it is set to a smaller value, larger incoming packets will be truncated. Default is 1472.

UIP_CONF_MAX_CONNECTIONS
  • The maximum number of UDP or TCP connections the server can handle simultaneously. Default is 20.
UIP_CONF_MAX_LISTENPORTS
  • The maximum number of UDP or TCP ports the server can listen to simultaneously. Default is 20.
XTCP_USE_SEPARATE_MAC
  • Defining this as 1 will cause the module to assume it will connect to a separate layer 2 MAC using xtcp_server(). By default this is not enabled.
XTCP_EXCLUDE_LISTEN
  • Exclude support for the listen command from the server, reducing memory footprint
  • Not defined
XTCP_EXCLUDE_UNLISTEN
  • Exclude support for the unlisten command from the server, reducing memory footprint
XTCP_EXCLUDE_CONNECT
  • Exclude support for the connect command from the server, reducing memory footprint
XTCP_EXCLUDE_BIND_REMOTE
  • Exclude support for the bind_remote command from the server, reducing memory footprint
XTCP_EXCLUDE_BIND_LOCAL
  • Exclude support for the bind_local command from the server, reducing memory footprint
XTCP_EXCLUDE_INIT_SEND
  • Exclude support for the init_send command from the server, reducing memory footprint
XTCP_EXCLUDE_SET_APPSTATE
  • Exclude support for the set_appstate command from the server, reducing memory footprint
XTCP_EXCLUDE_ABORT
  • Exclude support for the abort command from the server, reducing memory footprint
XTCP_EXCLUDE_CLOSE
  • Exclude support for the close command from the server, reducing memory footprint
XTCP_EXCLUDE_SET_POLL_INTERVAL
  • Exclude support for the set_poll_interval command from the server, reducing memory footprint
XTCP_EXCLUDE_JOIN_GROUP
  • Exclude support for the join_group command from the server, reducing memory footprint
XTCP_EXCLUDE_LEAVE_GROUP
  • Exclude support for the leave_group command from the server, reducing memory footprint
XTCP_EXCLUDE_GET_MAC_ADDRESS
  • Exclude support for the get_mac_address command from the server, reducing memory footprint
XTCP_EXCLUDE_GET_IPCONFIG
  • Exclude support for the get_ipconfig command from the server, reducing memory footprint
XTCP_EXCLUDE_ACK_RECV
  • Exclude support for the ack_recv command from the server, reducing memory footprint
XTCP_EXCLUDE_ACK_RECV_MODE
  • Exclude support for the ack_recv_mode command from the server, reducing memory footprint
XTCP_EXCLUDE_PAUSE
  • Exclude support for the pause command from the server, reducing memory footprint
XTCP_EXCLUDE_UNPAUSE
  • Exclude support for the unpause command from the server, reducing memory footprint
UIP_USE_AUTOIP
  • By defining this as 0, the IPv4LL application is removed from the code. Do this to save approxmiately 1kB. Auto IP is a stateless protocol that assigns an IP address to a device. Typically, if a unit is trying to use DHCP to obtain an address, and a server cannot be found, then auto IP is used to assign an address of the form 169.254.x.y. Auto IP is enabled by default
UIP_USE_DHCP
  • By defining this as 0, the DHCP client is removed from the code. This will save approximately 2kB. DHCP is a protocol for dynamically acquiring an IP address from a centralised DHCP server. This option is enabled by default.

Data Structures/Types

  • xtcp_ipaddr_t

    XTCP IP address.

    This data type represents a single ipv4 address in the XTCP stack.

  • xtcp_ipconfig_t

    IP configuration information structure.

    This structure describes IP configuration for an ip node.

    Structure Members:

    • xtcp_ipaddr_t ipaddr

      The IP Address of the node.

    • xtcp_ipaddr_t netmask

      The netmask of the node.

      The mask used to determine which address are routed locally.

    • xtcp_ipaddr_t gateway

      The gateway of the node.

  • xtcp_protocol_t

    XTCP protocol type.

    This determines what type a connection is: either UDP or TCP.

    Enum Values:

    • XTCP_PROTOCOL_TCP

      Transmission Control Protocol.

    • XTCP_PROTOCOL_UDP

      User Datagram Protocol.

  • xtcp_event_type_t

    XTCP event type.

    The event type represents what event is occuring on a particualr connection. It is instantiated when an event is received by the client using the xtcp_event() function.

    Enum Values:

    • XTCP_NEW_CONNECTION

      This event represents a new connection has been made.

      In the case of a TCP server connections it occurs when a remote host firsts makes contact with the local host. For TCP client connections it occurs when a stream is setup with the remote host. For UDP connections it occurs as soon as the connection is created.

    • XTCP_RECV_DATA

      This event occurs when the connection has received some data.

      The client must follow receipt of this event with a call to xtcp_recv() before any other interaction with the server.

    • XTCP_REQUEST_DATA

      This event occurs when the server is ready to send data and is requesting that the client send data.

      This event happens after a call to xtcp_init_send() from the client. The client must follow receipt of this event with a call to xtcp_send() before any other interaction with the server.

    • XTCP_SENT_DATA

      This event occurs when the server has successfully sent the previous piece of data that was given to it via a call to xtcp_send().

      The server is now requesting more data so the client must** follow receipt of this event with a call to xtcp_send() before any other interaction with the server.

    • XTCP_RESEND_DATA

      This event occurs when the server has failed to send the previous piece of data that was given to it via a call to xtcp_send().

      The server is now requesting for the same data to be sent again. The client must** follow receipt of this event with a call to xtcp_send() before any other interaction with the server.

    • XTCP_TIMED_OUT

      This event occurs when the connection has timed out with the remote host (TCP only).

      This event represents the closing of a connection and is the last event that will occur on an active connection.

    • XTCP_ABORTED

      This event occurs when the connection has been aborted by the local or remote host (TCP only).

      This event represents the closing of a connection and is the last event that will occur on an active connection.

    • XTCP_CLOSED

      This event occurs when the connection has been closed by the local or remote host.

      This event represents the closing of a connection and is the last event that will occur on an active connection.

    • XTCP_POLL

      This event occurs at regular intervals per connection.

      Polling can be initiated and the interval can be set with xtcp_set_poll_interval()

    • XTCP_IFUP

      This event occurs when the link goes up (with valid new ip address).

      This event has no associated connection.

    • XTCP_IFDOWN

      This event occurs when the link goes down.

      This event has no associated connection.

    • XTCP_ALREADY_HANDLED

      This event type does not get set by the server but can be set by the client to show an event has been handled.

  • xtcp_connection_type_t

    Type representing a connection type.

    Enum Values:

    • XTCP_CLIENT_CONNECTION

      A client connection.

    • XTCP_SERVER_CONNECTION

      A server connection.

  • xtcp_connection_t

    This type represents a TCP or UDP connection.

    This is the main type containing connection information for the client to handle. Elements of this type are instantiated by the xtcp_event() function which informs the client about an event and the connection the event is on.

    Structure Members:

    • int id

      A unique identifier for the connection.

    • xtcp_protocol_t protocol

      The protocol of the connection (TCP/UDP)

    • xtcp_connection_type_t connection_type

      The type of connection (client/sever)

    • xtcp_event_type_t event

      The last reported event on this connection.

    • xtcp_appstate_t appstate

      The application state associated with the connection.

      This is set using the xtcp_set_connection_appstate() function.

    • xtcp_ipaddr_t remote_addr

      The remote ip address of the connection.

    • unsigned int remote_port

      The remote port of the connection.

    • unsigned int local_port

      The local port of the connection.

    • unsigned int mss

      The maximum size in bytes that can be send using xtcp_send() after a send event.

Server API

  • void xtcp_server(chanend mac_rx, chanend mac_tx, chanend xtcp[], int num_xtcp_clients, xtcp_ipconfig_t &?ipconfig)

    xtcp TCP/IP server.

    This function implements an xtcp tcp/ip server in a logical core. It uses a port of the uIP stack which is then interfaces over the xtcp channel array.

    The IP setup is based on the ipconfig parameter. If this parameter is NULL then an automatic IP address is found (using dhcp or ipv4 link local addressing if no dhcp server is present). Otherwise it uses the ipconfig structure to allocate a static ip address.

    The clients can communicate with the server using the API found in xtcp_client.h

    Parameters

    • mac_rx

      Rx channel connected to ethernet server

    • mac_tx

      Tx channel connected to ethernet server

    • xtcp

      Client channel array

    • num_xtcp_clients

      The number of clients connected to the server

    • ipconfig

      An data structure representing the IP config (ip address, netmask and gateway) of the device. Leave NULL for automatic address allocation.

    • connect_status

      This chanend needs to be connected to the connect status output of the ethernet mac.

  • void ethernet_xtcp_server(ethernet_xtcp_ports_t &ports, xtcp_ipconfig_t &ipconfig, chanend xtcp[], int n)

Client API

Event Receipt

  • transaction xtcp_event(chanend c_xtcp, xtcp_connection_t &conn)

    Receive the next connect event.

    Upon receiving the event, the xtcp_connection_t structure conn is instatiated with information of the event and the connection it is on.

    This can be used in a select statement.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      the connection relating to the current event

Setting Up Connections

  • void xtcp_listen(chanend c_xtcp, int port_number, xtcp_protocol_t proto)

    Listen to a particular incoming port.

    After this call, when a connection is established an XTCP_NEW_CONNECTION event is signalled.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • port_number

      the local port number to listen to

    • proto

      the protocol to listen to (TCP or UDP)

  • void xtcp_unlisten(chanend c_xtcp, int port_number)

    Stop listening to a particular incoming port.

    Applies to TCP connections only.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • port_number

      local port number to stop listening on

  • void xtcp_connect(chanend c_xtcp, int port_number, xtcp_ipaddr_t ipaddr, xtcp_protocol_t proto)

    Try to connect to a remote port.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • port_number

      the remote port to try to connect to

    • ipaddr

      the ip addr of the remote host

    • proto

      the protocol to connect with (TCP or UDP)

  • void xtcp_bind_local(chanend c_xtcp, xtcp_connection_t &conn, int port_number)

    Bind the local end of a connection to a particular port (UDP).

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      the connection

    • port_number

      the local port to set the connection to

  • void xtcp_bind_remote(chanend c_xtcp, xtcp_connection_t &conn, xtcp_ipaddr_t addr, int port_number)

    Bind the remote end of a connection to a particular port and ip address.

    This is only valid for XTCP_PROTOCOL_UDP connections. After this call, packets sent to this connection will go to the specified address and port

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      the connection

    • addr

      the intended remote address of the connection

    • port_number

      the intended remote port of the connection

  • void xtcp_set_connection_appstate(chanend c_xtcp, xtcp_connection_t &conn, xtcp_appstate_t appstate)

    Set the connections application state data item.

    After this call, subsequent events on this connection will have the appstate field of the connection set

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      the connection

    • appstate

      An unsigned integer representing the state. In C this is usually a pointer to some connection dependent information.

Receiving Data

  • int xtcp_recv(chanend c_xtcp, char data[])

    Receive data from the server.

    This can be called after an XTCP_RECV_DATA event.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • data

      A array to place the received data into

    Returns

    The length of the received data in bytes

  • int xtcp_recvi(chanend c_xtcp, char data[], int i)

    Receive data from the xtcp server.

    This can be called after an XTCP_RECV_DATA event.

    The data is put into the array data starting at index i i.e. the first byte of data is written to data[i].

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • data

      A array to place the received data into

    • i

      The index where to start filling the data array

    Returns

    The length of the received data in bytes

  • int xtcp_recv_count(chanend c_xtcp, char data[], int count)

    Receive a number of bytes of data from the xtcp server.

    This can be called after an XTCP_RECV_DATA event.

    Data is pulled from the xtcp server and put into the array, until either there is no more data to pull, or until count bytes have been received. If there are more bytes to be received from the server then the remainder are discarded. The return value reflects the number of bytes pulled from the server, not the number stored in the buffer. From this the user can determine if they have lost some data.

    see the buffer client protocol for a mechanism for receiving bytes without discarding the extra ones.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • data

      A array to place the received data into

    • count

      The number of bytes to receive

    Returns

    The length of the received data in bytes, whether this was more or less than the requested amount.

Sending Data

  • void xtcp_init_send(chanend c_xtcp, xtcp_connection_t &conn)

    Initiate sending data on a connection.

    After making this call, the server will respond with a XTCP_REQUEST_DATA event when it is ready to accept data.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      the connection

  • void xtcp_send(chanend c_xtcp, char ? data[], int len)

    Send data to the xtcp server.

    Send data to the server. This should be called after a XTCP_REQUEST_DATA, XTCP_SENT_DATA or XTCP_RESEND_DATA event (alternatively xtcp_write_buf can be called). To finish sending this must be called with a length of zero or call the xtcp_complete_send() function.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • data

      An array of data to send

    • len

      The length of data to send. If this is 0, no data will be sent and a XTCP_SENT_DATA event will not occur.

  • void xtcp_sendi(chanend c_xtcp, char ? data[], int i, int len)

    Send data to the xtcp server.

    Send data to the server. This should be called after a XTCP_REQUEST_DATA, XTCP_SENT_DATA or XTCP_RESEND_DATA event (alternatively xtcp_write_buf can be called). The data is sent starting from index i i.e. data[i] is the first byte to be sent. To finish sending this must be called with a length of zero.

    Parameters

    • c_xtcp

      chanend connected to the xtcp serve

    • data

      An array of data to send

    • i

      The index at which to start reading from the data array

    • len

      The length of data to send. If this is 0, no data will be sent and a XTCP_SENT_DATA event will not occur.

  • void xtcp_complete_send(chanend c_xtcp)

    Complete a send transaction with the server.

    This function can be called after a XTCP_REQUEST_DATA, XTCP_SENT_DATA or XTCP_RESEND_DATA event to finish any sending on the connection that the event related to.

    Parameters

    • c_xtcp

      chanend connected to the tcp server

Other Connection Management

  • void xtcp_set_poll_interval(chanend c_xtcp, xtcp_connection_t &conn, int poll_interval)

    Set UDP poll interval.

    When this is called then the udp connection will cause a poll event every poll_interval milliseconds.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      the connection

    • poll_interval

      the required poll interval in milliseconds

  • void xtcp_close(chanend c_xtcp, xtcp_connection_t &conn)

    Close a connection.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      the connection

  • void xtcp_abort(chanend c_xtcp, xtcp_connection_t &conn)

    Abort a connection.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      the connection

  • void xtcp_pause(chanend c_xtcp, xtcp_connection_t &conn)

    pause a connection.

    No further reads and writes will occur on the network.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      tcp connection structure

  • void xtcp_unpause(chanend c_xtcp, xtcp_connection_t &conn)

    unpause a connection

    Activity is resumed on a connection.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • conn

      tcp connection structure

Other General Client Functions

  • void xtcp_join_multicast_group(chanend c_xtcp, xtcp_ipaddr_t addr)

    Subscribe to a particular ip multicast group address.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • addr

      The address of the multicast group to join. It is assumed that this is a multicast IP address.

  • void xtcp_leave_multicast_group(chanend c_xtcp, xtcp_ipaddr_t addr)

    Unsubscribe to a particular ip multicast group address.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • addr

      The address of the multicast group to leave. It is assumed that this is a multicast IP address which has previously been joined.

  • void xtcp_get_mac_address(chanend c_xtcp, unsigned char mac_addr[])

    Get the current host MAC address of the server.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • mac_addr

      the array to be filled with the mac address

  • void xtcp_get_ipconfig(chanend c_xtcp, xtcp_ipconfig_t &ipconfig)

    Get the IP config information into a local structure.

    Get the current host IP configuration of the server.

    Parameters

    • c_xtcp

      chanend connected to the xtcp server

    • ipconfig

      the structure to be filled with the IP configuration information

High-level blocking client API

  • void xtcp_wait_for_ifup(chanend tcp_svr)

    block until the xtcp interface has come up

    This means, amongst other things, that it has acquired an IP address using whatever scheme was necessary

  • xtcp_connection_t xtcp_wait_for_connection(chanend tcp_svr)

    Block until a connection attempt to is made.

  • int xtcp_write(chanend tcp_svr, xtcp_connection_t &conn, unsigned char buf[], int len)

    Write a buffer of data to a TCP connection.

    This is a blocking write of data to the given xtcp connection

    Parameters

    • tcp_svr

      The xtcp control channel

    • conn

      The xtcp server connection structure

    • buf

      The buffer to write

    • len

      The length of data to send

    Returns

    1 for success, 0 for failure

  • int xtcp_read(chanend tcp_svr, xtcp_connection_t &conn, unsigned char buf[], int minlen)

    Receive data from xtcp connection.

    This is a blocking read from the xtcp stack

    Parameters

    • tcp_svr

      The xtcp control channel

    • conn

      The xtcp server connection structure

    • buf

      The buffer to read into

    • minlen

      The minimim length of data to receive

    Returns

    The number of bytes received

High-level buffered client API

  • void xtcp_buffered_set_rx_buffer(chanend tcp_svr, xtcp_connection_t *conn, xtcp_bufinfo_t *bufinfo, char *buf, int buflen)

    set the location and size of the receiver buffer

    Parameters

    • tcp_svr

      the xtcp server control channel

    • conn

      a pointer to the xtcp connection info structure

    • bufinfo

      a pointer to the buffered API control structure

    • buf

      a pointer to the buffer to use for received data

    • buflen

      the length of the receive buffer in bytes

  • void xtcp_buffered_set_tx_buffer(chanend tcp_svr, xtcp_connection_t *conn, xtcp_bufinfo_t *bufinfo, char *buf, int buflen, int lowmark)

    set the location and size of the transmission buffer

    the size of the buffer should probably be no smaller than XTCP_CLIENT_BUF_SIZE plus the maximum buffered message length. if it is, then buffer overflow can be detected and data will be lost.

    Parameters

    • tcp_svr

      the xtcp server control channel

    • conn

      a pointer to the xtcp connection info structure

    • bufinfo

      a pointer to the buffered API control structure

    • buf

      a pointer to the buffer to use for received data

    • buflen

      the length of the receive buffer in bytes

    • lowmark

      if the number of spare bytes in the buffer falls below this, TCP pauses the stream

  • int xtcp_buffered_recv(chanend tcp_svr, xtcp_connection_t *conn, xtcp_bufinfo_t *bufinfo, char **buf, int len, int *overflow)

    Pull a buffer of data out of the received data buffer.

    This pulls a specified length of data from the data buffer. It is most useful for protocols where the packet format is known, or at least where variable sized data blocks are preceeded by a length field. A good example is DHCP.

    When calling this in response to a XTCP_RECV_DATA event, and you must keep calling it until it returns zero.

    The return value is either:

    when the user wants to pull N bytes from the buffer, but less than N have been received into it, then the function returns zero. In this case, a calling function would typically not process further until another receive event was detected, indicating that there is some more data available in to read, and therefore that the number of bytes requested can now be fullfilled.

    consider the data pointed to by the buf parameter to be read only. It points into the allocated buffer

    Parameters

    • tcp_svr

      the xtcp server control channel

    • conn

      a pointer to the xtcp connection info structure

    • bufinfo

      a pointer to the buffered API control structure

    • buf

      on return this points to the received data.

    • len

      length of the buffer to receive into

    • overflow

      pointer to an int which is set to non-zero if the buffer overflowed

    Returns

    the number of characters received in the buffer, or zero if we have used up all of the data, or the space available when receiving more data from xtcp would overflow the buffer

  • int xtcp_buffered_recv_upto(chanend tcp_svr, xtcp_connection_t *conn, xtcp_bufinfo_t *bufinfo, char **buf, char delim, int *overflow)

    Receive data from the receive buffer, up to a given delimiter character.

    Many protocols, eg SMTP, FTP, HTTP, have variable length records with delimiters at the end of the record. This function can be used to fetch data from that type of data stream.

    When calling this in response to a XTCP_RECV_DATA event, and you must keep calling it until it returns zero.

    The returned length contains the delimiter

    Parameters

    • tcp_svr

      the xtcp server control channel

    • conn

      a pointer to the xtcp connection info structure

    • bufinfo

      a pointer to the buffered API control structure

    • buf

      on return this points to the received data.

    • delim

      a character to receive data until

    • overflow

      pointer to an int which is set to non-zero if the buffer overflowed

    Returns

    the number of characters in the returned data (including delimiter), or zero when there is nothing to receive, or the space available when receiving more data from xtcp would overflow the buffer

  • int xtcp_buffered_send(chanend tcp_svr, xtcp_connection_t *conn, xtcp_bufinfo_t *bufinfo, char *buf, int len)

    Add more data to the send buffer.

    Parameters

    • tcp_svr

      the xtcp server control channel

    • conn

      a pointer to the xtcp connection info structure

    • bufinfo

      a pointer to the buffered API control structure

    • buf

      a buffer of data to queue for sending

    • len

      the length of the data in the buffer

    Returns

    1 if the data was able to be buffered for send, 0 otherwise

  • void xtcp_buffered_send_handler(chanend tcp_svr, xtcp_connection_t *conn, xtcp_bufinfo_t *bufinfo)

    The handler function for transmission requests from the xtcp stack.

    When one of the following event types is received from the xtcp server channel then this method should be called.

    XTCP_SENT_DATA XTCP_REQUEST_DATA XTCP_RESEND_DATA

    Parameters

    • tcp_svr

      the xtcp server control channel

    • conn

      a pointer to the xtcp connection info structure

    • bufinfo

      a pointer to the buffered API control structure

  • int xtcp_buffered_send_buffer_remaining(xtcp_bufinfo_t *bufinfo)

    Get the remaining amount of space in the send buffer.

    A client can use this to determine whether the outgoing buffer has enough space to accept more data before the call to send that data is made.

    Parameters

    • bufinfo

      a pointer to the buffered API control structure

    Returns

    the number of bytes remaining in the send buffer

See Also