dcDCPL_Socket.h File Reference

DPWSCore IP sockets portability layer. More...

#include "dcpl_target.h"
#include "dcDCPL_Error.h"
#include <string.h>

Data Structures

struct  socket_data
 Structure for TCP sockets options. More...

Defines

#define DCPL_AF_INET   0x1
 DCPL IP v4 address family (bit flag).
#define DCPL_AF_INET6   0x2
 DCPL IP v6 address family (bit flag).

Typedefs

typedef struct socket_data socket_data_t
 Structure for TCP sockets options.

Functions

DCPL_SOCKET dcpl_udp_open (int family, struct dcpl_error *error)
 Opens an UDP socket for sending datagrams.
int dcpl_set_multicast_netif (DCPL_SOCKET s, int family, uint32_t itf_selector, struct dcpl_error *error)
 Selects the network interface for sending multicast datagrams on a UDP socket.
DCPL_SOCKET dcpl_udp_bind (int family, const char *itf_addr, uint32_t itf_selector, uint16_t port, int bind_flags, struct dcpl_error *error)
 Opens an UDP socket for receiving datagrams.
DCPL_SOCKET dcpl_multicast_bind (int family, const char *itf_addr, uint32_t itf_selector, uint16_t port, const char *multicast_addr, struct dcpl_error *error)
 Opens an UDP socket for receiving multicast datagrams.
int dcpl_udp_send (DCPL_SOCKET s, const char *buf, size_t n, int flags, const char *host, uint32_t itf_selector, uint16_t port, struct dcpl_error *error)
 Sends a datagram on an opened UDP socket.
int dcpl_udp_send_loopback (DCPL_SOCKET s, const char *buf, size_t n, int flags, int af, unsigned short port, struct dcpl_error *error)
 Sends locally a datagram on an UDP socket using the loopback interface.
int dcpl_udp_recv (DCPL_SOCKET s, char *buf, size_t n, int flags, char *peer_addr, int addr_len, uint16_t *peer_port, uint32_t *itf, struct dcpl_error *error)
 Receives a datagram on a bound UDP socket.
DCPL_SOCKET dcpl_tcp_bind_listener (int family, const char *itf_addr, uint32_t itf_selector, uint16_t port, int backlog, socket_data_t *bind_data, struct dcpl_error *error)
 Opens a socket for receiving incoming TCP connections.
DCPL_SOCKET dcpl_tcp_accept (DCPL_SOCKET listener, socket_data_t *data, char *peer_addr, int addr_len, uint16_t *peer_port, uint32_t *itf, struct dcpl_error *error)
 Creates a socket for an incoming TCP connection.
DCPL_SOCKET dcpl_tcp_connect (const char *host, uint32_t itf_selector, uint16_t port, int timeout, socket_data_t *data, struct dcpl_error *error)
 Creates and connects a TCP socket to a remote host.
int dcpl_tcp_get_local_address (DCPL_SOCKET s, char *local_addr_buf, int buf_size, struct dcpl_error *error)
 Retrieves the local address for a TCP connected socket.
int dcpl_tcp_shutdown (DCPL_SOCKET s, int how, struct dcpl_error *error)
 Stops receive/send operations on a connected TCP socket.
int dcpl_tcp_send (DCPL_SOCKET s, const char *buf, size_t n, int flags, int timeout, struct dcpl_error *error)
 Sends data on a connected TCP socket.
int dcpl_tcp_recv (DCPL_SOCKET s, char *buf, size_t n, int flags, int timeout, struct dcpl_error *error)
 Reads data on a connected TCP socket.
int dcpl_tcp_peek (DCPL_SOCKET s, char *buf, size_t n, int flags, int timeout, struct dcpl_error *error)
 Peeks data on a connected TCP socket.
int dcpl_tcp_socket_valid (DCPL_SOCKET s)
 Test a connected socket is still alive (not the connection actually).
int dcpl_closesocket (DCPL_SOCKET s, struct dcpl_error *error)
 Frees all resources associated with any type of socket.


Detailed Description

DPWSCore IP sockets portability layer.


Define Documentation

#define DCPL_AF_INET   0x1

DCPL IP v4 address family (bit flag).

#define DCPL_AF_INET6   0x2

DCPL IP v6 address family (bit flag).


Typedef Documentation

typedef struct socket_data socket_data_t

Structure for TCP sockets options.


Function Documentation

DCPL_SOCKET dcpl_udp_open ( int  family,
struct dcpl_error error 
)

Opens an UDP socket for sending datagrams.

Parameters:
family The address family for the socket (DCPL_AF_INET or DCPL_AF_INET6)
[out] error A structure to get detailed error information.
Returns:
DCPL_OK or any DCPL error code.

int dcpl_set_multicast_netif ( DCPL_SOCKET  s,
int  family,
uint32_t  itf_selector,
struct dcpl_error error 
)

Selects the network interface for sending multicast datagrams on a UDP socket.

Parameters:
s The UDP socket descriptor.
family The address family of the socket (DCPL_AF_INET or DCPL_AF_INET6)
itf_selector The index of the interface to be selected. This index is the interface number for IPv6 (field itf_nb in dcpl_ip_addr_t), the local IP address in its numeric form for IPv4 (field ipv4_addr in dcpl_ip_addr_t).
[out] error A structure to get detailed error information.
Returns:
DCPL_OK or any DCPL error code.

DCPL_SOCKET dcpl_udp_bind ( int  family,
const char *  itf_addr,
uint32_t  itf_selector,
uint16_t  port,
int  bind_flags,
struct dcpl_error error 
)

Opens an UDP socket for receiving datagrams.

Parameters:
family The address family for the socket (DCPL_AF_INET or DCPL_AF_INET6)
itf_addr The local IP address on which listening (selects the interface).
itf_selector The interface index for the itf_addr address. Required for IPv6 link-local listening addresses (else 0). Should be ignored for IPv4.
port The local UDP port on which listening.
bind_flags Standard BSD bitwise boolean socket options passed directly by the API user.
[out] error A structure to get detailed error information.
Returns:
DCPL_OK or any DCPL error code.

DCPL_SOCKET dcpl_multicast_bind ( int  family,
const char *  itf_addr,
uint32_t  itf_selector,
uint16_t  port,
const char *  multicast_addr,
struct dcpl_error error 
)

Opens an UDP socket for receiving multicast datagrams.

Parameters:
family The address family for the socket (DCPL_AF_INET or DCPL_AF_INET6)
itf_addr The local IP address on which listening (selects the interface).
itf_selector The interface index for the itf_addr address. Required for IPv6 link-local listening addresses (else 0). Should be ignored for IPv4.
port The local UDP port on which listening.
multicast_addr The multicast address of the group on which listening.
[out] error A structure to get detailed error information.
Returns:
DCPL_OK or any DCPL error code.

int dcpl_udp_send ( DCPL_SOCKET  s,
const char *  buf,
size_t  n,
int  flags,
const char *  host,
uint32_t  itf_selector,
uint16_t  port,
struct dcpl_error error 
)

Sends a datagram on an opened UDP socket.

Parameters:
s The UDP socket descriptor.
buf The character buffer containing the datagram to send.
n The number of characters of the datagram in buf.
flags Standard "send" flags passed transparently to the BSD implementation.
host The IP address (IPv4 or v6) of the destination host in its string form.
itf_selector The local interface index on which to send the datagram required for sending when the destination host uses a link-local IPv6 address (else 0). Should be ignored for IPv4.
port The destination UDP port.
[out] error A structure to get detailed error information.
Returns:
The number of bytes actually sent or any negative DCPL error code.

int dcpl_udp_send_loopback ( DCPL_SOCKET  s,
const char *  buf,
size_t  n,
int  flags,
int  af,
unsigned short  port,
struct dcpl_error error 
)

Sends locally a datagram on an UDP socket using the loopback interface.

Parameters:
s The UDP socket descriptor.
buf The character buffer containing the datagram to send.
n The number of characters of the datagram in buf.
flags Standard "send" flags passed transparently to the BSD implementation.
af The address family of the socket in order to select the correct loopback address.
port The UDP port on which to send the datagram.
[out] error A structure to get detailed error information.
Returns:
The number of bytes actually sent or any negative DCPL error code.

int dcpl_udp_recv ( DCPL_SOCKET  s,
char *  buf,
size_t  n,
int  flags,
char *  peer_addr,
int  addr_len,
uint16_t *  peer_port,
uint32_t *  itf,
struct dcpl_error error 
)

Receives a datagram on a bound UDP socket.

Parameters:
s The UDP socket descriptor.
buf The character buffer for receiving the datagram.
n The number of characters available for the datagram in buf.
flags Standard "receive" flags passed transparently to the BSD implementation.
[out] peer_addr Optional (nullable) buffer for receiving the peer address. This buffer should be long enough to receive an IPv4 or IPv6 address according to the address on which the socket is bound.
addr_len The length of the provided peer_addr buffer.
[out] peer_port The peer port. May be null if not required.
[out] itf The reception interface corresponding to the field itf_nb in dcpl_ip_addr_t for both IPv4 and IPv6. May be null if not required.
[out] error A structure to get detailed error information.
Returns:
The number of bytes actually received or any negative DCPL error code.

DCPL_SOCKET dcpl_tcp_bind_listener ( int  family,
const char *  itf_addr,
uint32_t  itf_selector,
uint16_t  port,
int  backlog,
socket_data_t bind_data,
struct dcpl_error error 
)

Opens a socket for receiving incoming TCP connections.

Parameters:
family The address family for the socket (DCPL_AF_INET or DCPL_AF_INET6)
itf_addr The local IP address on which listening.
itf_selector The interface index for the itf_addr address. Required for IPv6 link-local listening addresses (else 0). Should be ignored for IPv4.
port The local TCP port on which listening.
backlog The TCP backlog (i.e. The number of pending incoming connections).
bind_data The TCP options to use for the listening socket.
[out] error A structure to get detailed error information.
Returns:
DCPL_OK or any DCPL error code.

DCPL_SOCKET dcpl_tcp_accept ( DCPL_SOCKET  listener,
socket_data_t data,
char *  peer_addr,
int  addr_len,
uint16_t *  peer_port,
uint32_t *  itf,
struct dcpl_error error 
)

Creates a socket for an incoming TCP connection.

Parameters:
listener The descriptor of the listening socket.
data The TCP options to set on the new socket.
[out] peer_addr Optional (nullable) buffer for receiving the peer address. This buffer should be long enough to receive an IPv4 or IPv6 address according to the address on which the listening socket is bound.
addr_len The length of the provided peer_addr buffer.
[out] peer_port The peer port. May be null if not required.
[out] itf The reception interface corresponding to the field itf_nb in dcpl_ip_addr_t for both IPv4 and IPv6. May be null if not required.
[out] error A structure to get detailed error information.
Returns:
DCPL_OK or any DCPL error code.

DCPL_SOCKET dcpl_tcp_connect ( const char *  host,
uint32_t  itf_selector,
uint16_t  port,
int  timeout,
socket_data_t data,
struct dcpl_error error 
)

Creates and connects a TCP socket to a remote host.

Parameters:
host The IP address (IPv4 or v6) of the destination host in its string form.
itf_selector The local interface index on which to send the datagram required for sending when the destination host uses a link-local IPv6 address (else 0). Should be ignored for IPv4.
port The destination UDP port.
timeout The timeout in milliseconds for the connection. Should block if 0.
data The TCP options to set on the new socket before the connection.
[out] error A structure to get detailed error information.
Returns:
A descriptor for the connected socket or DCPL_INVALID_SOCKET in case of error.

int dcpl_tcp_get_local_address ( DCPL_SOCKET  s,
char *  local_addr_buf,
int  buf_size,
struct dcpl_error error 
)

Retrieves the local address for a TCP connected socket.

Can be used after calling dcpl_tcp_connect to establish which route has been used by the IP stack.

Parameters:
s The connected socket descriptor.
[out] local_addr_buf Buffer for receiving the local address. This buffer should be long enough to receive an IPv4 or IPv6 address according to the address that was used to connect the socket.
buf_size The length of the provided local_addr_buf buffer.
[out] error A structure to get detailed error information.
Returns:
DCPL_OK or any DCPL error code.

int dcpl_tcp_shutdown ( DCPL_SOCKET  s,
int  how,
struct dcpl_error error 
)

Stops receive/send operations on a connected TCP socket.

Straightforward BSD semantics.

Parameters:
s The connected socket descriptor.
how 0 (stops readings), 1 (stops writings) or 2 (stop both).
[out] error A structure to get detailed error information.
Returns:
DCPL_OK or any DCPL error code.

int dcpl_tcp_send ( DCPL_SOCKET  s,
const char *  buf,
size_t  n,
int  flags,
int  timeout,
struct dcpl_error error 
)

Sends data on a connected TCP socket.

Parameters:
s The TCP socket descriptor.
buf The character buffer containg the data to send.
n The number of characters to be sent in buf.
flags Standard "send" flags passed transparently to the BSD implementation.
timeout The timeout in milliseconds for the sending operation. Should block if 0.
[out] error A structure to get detailed error information.
Returns:
The number of bytes actually sent or any negative DCPL error code.

int dcpl_tcp_recv ( DCPL_SOCKET  s,
char *  buf,
size_t  n,
int  flags,
int  timeout,
struct dcpl_error error 
)

Reads data on a connected TCP socket.

Parameters:
s The connected TCP socket descriptor.
buf The character buffer for receiving the data.
n The number of characters available for the data in buf.
flags Standard "receive" flags passed transparently to the BSD implementation.
timeout The timeout in milliseconds for the reception operation. Should block if 0.
[out] error A structure to get detailed error information.
Returns:
The number of bytes actually received or any negative DCPL error code.

int dcpl_tcp_peek ( DCPL_SOCKET  s,
char *  buf,
size_t  n,
int  flags,
int  timeout,
struct dcpl_error error 
)

Peeks data on a connected TCP socket.

Similar do dcpl_tcp_recv except that the data is not removed from the stream and is still available for reading.

Parameters:
s The connected TCP socket descriptor.
buf The character buffer for receiving the data.
n The number of characters available for the data in buf.
flags Standard "receive" flags passed transparently to the BSD implementation.
timeout The timeout in milliseconds for the reception operation. Should block if 0.
[out] error A structure to get detailed error information.
Returns:
The number of bytes actually received or any negative DCPL error code.

int dcpl_tcp_socket_valid ( DCPL_SOCKET  s  ) 

Test a connected socket is still alive (not the connection actually).

Note that this call can only check that a socket has received a graceful shutdown from the peer or that the "keep-alive" message (that may have been turned on with TCP option) has failed. However this last is genrally sent after several hours of inactivity...

Parameters:
s The connected TCP socket descriptor.
Returns:
0 if the socket is unconnected. 1 else if nothing was detected.

int dcpl_closesocket ( DCPL_SOCKET  s,
struct dcpl_error error 
)

Frees all resources associated with any type of socket.

May close a TCP connection if running.

Parameters:
s The socket descriptor to close.
[out] error A structure to get detailed error information.
Returns:
DCPL_OK or any DCPL error code.


Generated on Fri Apr 17 15:18:24 2009 for DPWSCore by  doxygen 1.5.8