dktcpip.h File Reference

Portable TCP/IP and UDP client API. More...

#include <dk.h>
#include <dktypes.h>

Go to the source code of this file.

Defines

#define DK_IP_ADDR_REMOTE_WISHED   0
 Retrieve address: Remote address wanted.
#define DK_IP_ADDR_REMOTE_FOUND   1
 Retrieve address: Remote address found.
#define DK_IP_ADDR_LOCAL_WISHED   2
 Retrieve address: Local address wanted.
#define DK_IP_ADDR_LOCAL_FOUND   3
 Retrieve address: Local address found.

Functions

int dktcpip_start (void)
 Start TCP/IP subsystem.
int dktcpip_end (void)
 End TCP/IP subsystem.
dk_tcpip_tdktcpip_new (void)
 Create new TCP/IP support structure.
void dktcpip_delete (dk_tcpip_t *t)
 Destroy TCP/IP support structure created by dktcpip_new() and release memory.
void dktcpip_init (dk_tcpip_t *t)
 Initialize TCP/IP support structure (for static variables not created by dktcpip_new()).
dk_ip_addr_tdktcpip_get_addr (dk_tcpip_t *t, int w)
 Get pointer to address structure of TCP/IP support structure.
int dktcpipaddr_set_ip_byname (dk_ip_addr_t *a, char *h, dk_tcpip_t *t)
 Set address structure to point to a given host.
int dktcpipaddr_set_ip_loopback (dk_ip_addr_t *a)
 Set address structure to loopback interface address.
int dktcpipaddr_set_ip_local (dk_ip_addr_t *a, dk_tcpip_t *t)
 Set address structure to local IP address.
int dktcpipaddr_set_ip_any (dk_ip_addr_t *a)
 Set address structure to use any address.
int dktcpip_addr_set_port (\dk_ip_addr_t *a, unsigned short min, unsigned short max)
 Set port range for address.
int dktcpip_set_connectionless (dk_tcpip_t *t, int f)
 Set up connection-oriented (TCP) or connectionless (UDP) use.
int dktcpip_up (dk_tcpip_t *t)
 Bring endpoint up.
int dktcpip_down (dk_tcpip_t *t)
 Shut down endpoint.
int dktcpip_read (dk_tcpip_t *t, char *b, size_t *l)
 Receive data.
int dktcpip_write (dk_tcpip_t *t, char *b, size_t *l)
 Send data.
int dktcpip_is_rdclosed (dk_tcpip_t *t)
 Check whether the end of data already was found.
int dktcpip_closewrite (dk_tcpip_t *t)
 Shutdown endpoint for write operations.
int dktcpip_set_nonblock (dk_tcpip_t *t, int f)
 Set endpoint to non-blocking mode.
int dktcpip_set_timeout (dk_tcpip_t *t, double o)
 Set timeout for operations.
int dktcpip_respond (dk_tcpip_t *t)
 Set remote wished address to remote found address.
int dktcpip_set_reuse (dk_tcpip_t *t, int f)
 Set reuse flag for endpoint.
int dktcpip_set_broadcast (dk_tcpip_t *t, int f)
 Enable/disable broadcast for endpoint.
int dktcpip_set_keepalive (dk_tcpip_t *t, int f)
 Set keep-alive flag.
int dktcpip_get_error_code (dk_tcpip_t *t, int c)
 Get last error code, optionally clear error.


Detailed Description

Portable TCP/IP and UDP client API.


Define Documentation

#define DK_IP_ADDR_LOCAL_FOUND   3

Retrieve address: Local address found.

#define DK_IP_ADDR_LOCAL_WISHED   2

Retrieve address: Local address wanted.

#define DK_IP_ADDR_REMOTE_FOUND   1

Retrieve address: Remote address found.

#define DK_IP_ADDR_REMOTE_WISHED   0

Retrieve address: Remote address wanted.


Function Documentation

int dktcpip_addr_set_port ( \dk_ip_addr_t a,
unsigned short  min,
unsigned short  max 
)

Set port range for address.

Some applications might want to bind local addresses from a specific range. For the remote addresses the min and max parameter should be equal.

Parameters:
a Address structure.
min Minimum port number to use.
max Maximum port number to use.
Returns:
Flag to indicate success.

int dktcpip_closewrite ( dk_tcpip_t t  ) 

Shutdown endpoint for write operations.

This indicates that we will not write data to the endpoint. The peer will be notified about the end of data when attempting to read from the connection.

Parameters:
t TCP/IP support structure.
Returns:
Flag to indicate success.

void dktcpip_delete ( dk_tcpip_t t  ) 

Destroy TCP/IP support structure created by dktcpip_new() and release memory.

The endpoint is brought down if necessary.

Parameters:
t TCP/IP support structure.

int dktcpip_down ( dk_tcpip_t t  ) 

Shut down endpoint.

Orderly release (shutdown for writing, reading until no more data) for TCP connections, close file descriptor.

Parameters:
t TCP/IP support structure.
Returns:
Flag to indicate success.

int dktcpip_end ( void   ) 

End TCP/IP subsystem.

On Windows the TCP/IP subsystem should be brought down by applications which started it. On other systems this function simply does nothing.

Returns:
Flag to indicate success.

dk_ip_addr_t* dktcpip_get_addr ( dk_tcpip_t t,
int  w 
)

Get pointer to address structure of TCP/IP support structure.

Parameters:
t TCP/IP support structure.
w Indicator, which address to choose: DK_IP_ADDR_REMOTE_WISHED, DK_IP_ADDR_REMOTE_FOUND, DK_IP_ADDR_LOCAL_WISHED or DK_IP_ADDR_LOCAL_FOUND.
Returns:
Pointer to address on success, NULL on error.

int dktcpip_get_error_code ( dk_tcpip_t t,
int  c 
)

Get last error code, optionally clear error.

Parameters:
t TCP/IP support structure.
c Flag, clear error code.
Returns:
Last error occured with t.

void dktcpip_init ( dk_tcpip_t t  ) 

Initialize TCP/IP support structure (for static variables not created by dktcpip_new()).

Parameters:
t TCP/IP support structure.

int dktcpip_is_rdclosed ( dk_tcpip_t t  ) 

Check whether the end of data already was found.

Parameters:
t TCP/IP support structure.
Returns:
Flag to indicate end of data found.

dk_tcpip_t* dktcpip_new ( void   ) 

Create new TCP/IP support structure.

The structure is created in dynamically allocated memory, use dktcpip_delete() to destroy it and release the memory.

Returns:
Pointer to new structure on success, NULL on error.

int dktcpip_read ( dk_tcpip_t t,
char *  b,
size_t *  l 
)

Receive data.

Parameters:
t TCP/IP support structure.
b Buffer to receive data.
l Pointer to size variable (in: length of l in bytes, out: number of bytes received).
Returns:
Flag to indicate success. The function indicates success if the lower-level functions for the endpoint did not indicate errors. If the function returns successfully check the size variable whether or not any bytes were received.

int dktcpip_respond ( dk_tcpip_t t  ) 

Set remote wished address to remote found address.

For UDP endpoints the next datagram will be sent to the address the last datagram was received from.

Parameters:
t TCP/IP support structure.
Returns:
Flag to indicate success.

int dktcpip_set_broadcast ( dk_tcpip_t t,
int  f 
)

Enable/disable broadcast for endpoint.

Parameters:
t TCP/IP support structure.
f Flag, enable broadcast.
Returns:
Flag to indicate success.

int dktcpip_set_connectionless ( dk_tcpip_t t,
int  f 
)

Set up connection-oriented (TCP) or connectionless (UDP) use.

Parameters:
t TCP/IP support structure.
f Flag, use connectionless mode.
Returns:
Flag to indicate success.

int dktcpip_set_keepalive ( dk_tcpip_t t,
int  f 
)

Set keep-alive flag.

Parameters:
t TCP/IP support structure.
f New flag value.
Returns:
Flag to indicate success.

int dktcpip_set_nonblock ( dk_tcpip_t t,
int  f 
)

Set endpoint to non-blocking mode.

Parameters:
t TCP/IP support structure.
f Flag, use non-blocking mode.
Returns:
Flag to indicate success.

int dktcpip_set_reuse ( dk_tcpip_t t,
int  f 
)

Set reuse flag for endpoint.

Parameters:
t TCP/IP support structure.
f New flag value.
Returns:
Flag to indicate success.

int dktcpip_set_timeout ( dk_tcpip_t t,
double  o 
)

Set timeout for operations.

Parameters:
t TCP/IP support structure.
o Timeout in seconds.
Returns:
Flag to indicate success.

int dktcpip_start ( void   ) 

Start TCP/IP subsystem.

On Windows the TCP/IP protocol is not necessarily installed on a computer. This function checks whether the protocol is installed and attempts to load the DLLs. On other systems it does imply nothing.

Returns:
Flag to indicate success.

int dktcpip_up ( dk_tcpip_t t  ) 

Bring endpoint up.

This function brings the endpoint into a state allowing to send and receive data. Depending on whether TCP or UDP is used the endpoint is opened, a local address is bound and a connection is established (for TCP).

Parameters:
t TCP/IP support structure.
Returns:
Flag to indicate success.

int dktcpip_write ( dk_tcpip_t t,
char *  b,
size_t *  l 
)

Send data.

Parameters:
t TCP/IP support structure.
b Buffer containing the data to write.
l Pointer to length variable (in: size of b, out: number of bytes written)
Returns:
Flag to indicate success. The operation succeeds if the endpoints sending function does not indicate an error. Check the number of bytes written and compare it against the number of bytes to write to ensure all bytes are written properly if the function indicates success.

int dktcpipaddr_set_ip_any ( dk_ip_addr_t a  ) 

Set address structure to use any address.

This is useful for binding local addresses.

Parameters:
a Adress structure.
Returns:
Flag to indicate success.

int dktcpipaddr_set_ip_byname ( dk_ip_addr_t a,
char *  h,
dk_tcpip_t t 
)

Set address structure to point to a given host.

Parameters:
a Address structure.
h Host (IP address or host name).
t TCP/IP support structure. The error code (if any) is stored here.
Returns:
Flag to indicate success.

int dktcpipaddr_set_ip_local ( dk_ip_addr_t a,
dk_tcpip_t t 
)

Set address structure to local IP address.

Parameters:
a Adress structure.
t TCP/IP support structure. The error code (if any) is stored here.
Returns:
Flag to indicate success.

int dktcpipaddr_set_ip_loopback ( dk_ip_addr_t a  ) 

Set address structure to loopback interface address.

Parameters:
a Address structure.
Returns:
Flag to indicate success.


Generated on Mon Jan 4 15:50:56 2010 for dklibs by  doxygen 1.5.8