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 IP address.
This data type represents a single ipv4 address in the XTCP stack.
IP configuration information structure.
This structure describes IP configuration for an ip node.
Structure Members:
The IP Address of the node.
The netmask of the node.
The mask used to determine which address are routed locally.
The gateway of the node.
XTCP protocol type.
This determines what type a connection is: either UDP or TCP.
Enum Values:
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.
Type representing a connection type.
Enum Values:
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:
A unique identifier for the connection.
The protocol of the connection (TCP/UDP)
The type of connection (client/sever)
The last reported event on this connection.
The application state associated with the connection.
This is set using the xtcp_set_connection_appstate() function.
The remote ip address of the connection.
The remote port of the connection.
The local port of the connection.
The maximum size in bytes that can be send using xtcp_send() after a send event.
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.
Parameters: |
|
---|
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
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: |
|
---|
Listen to a particular incoming port.
After this call, when a connection is established an XTCP_NEW_CONNECTION event is signalled.
Parameters: |
|
---|
Stop listening to a particular incoming port.
Applies to TCP connections only.
Parameters: |
|
---|
Try to connect to a remote port.
Parameters: |
|
---|
Bind the local end of a connection to a particular port (UDP).
Parameters: |
|
---|
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: |
|
---|
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: |
|
---|
Receive data from the server.
This can be called after an XTCP_RECV_DATA event.
Parameters: |
|
---|---|
Returns: | The length of the received data in bytes |
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: |
|
---|---|
Returns: | The length of the received data in bytes |
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.
Parameters: |
|
---|
see the buffer client protocol for a mechanism for receiving bytes without discarding the extra ones.
Returns: | The length of the received data in bytes, whether this was more or less than the requested amount. |
---|
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: |
|
---|
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: |
|
---|
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: |
|
---|
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: |
|
---|
Set UDP poll interval.
When this is called then the udp connection will cause a poll event every poll_interval milliseconds.
Parameters: |
|
---|
Close a connection.
Parameters: |
|
---|
Abort a connection.
Parameters: |
|
---|
pause a connection.
No further reads and writes will occur on the network.
Parameters: |
|
---|
unpause a connection
Activity is resumed on a connection.
Parameters: |
|
---|
Subscribe to a particular ip multicast group address.
Parameters: |
|
---|
Unsubscribe to a particular ip multicast group address.
Parameters: |
|
---|
Get the current host MAC address of the server.
Parameters: |
|
---|
Get the IP config information into a local structure.
Get the current host IP configuration of the server.
Parameters: |
|
---|
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
Block until a connection attempt to is made.
Write a buffer of data to a TCP connection.
This is a blocking write of data to the given xtcp connection
Parameters: |
|
---|---|
Returns: | 1 for success, 0 for failure |
Receive data from xtcp connection.
This is a blocking read from the xtcp stack
Parameters: |
|
---|---|
Returns: | The number of bytes received |
set the location and size of the receiver buffer
Parameters: |
|
---|
set the location and size of the transmission buffer
Parameters: |
|
---|
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.
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.
Parameters: |
|
---|---|
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 |
consider the data pointed to by the buf parameter to be read only. It points into the allocated buffer
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: |
|
---|---|
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 |
Add more data to the send buffer.
Parameters: |
|
---|---|
Returns: | 1 if the data was able to be buffered for send, 0 otherwise |
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: |
|
---|
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: |
|
---|---|
Returns: | the number of bytes remaining in the send buffer |