Base class for IP Based Networking Libraries

Dependencies:   DnsQuery

Dependents:   TempTower BSDInterfaceTests HelloBSDInterface ESP8266InterfaceTests ... more

Embed: (wiki syntax)

« Back to documentation index

NetworkStack Class Reference

NetworkStack class. More...

#include <NetworkStack.h>

Public Member Functions

virtual const char * get_ip_address ()=0
 Get the local IP address.
virtual int gethostbyname (SocketAddress *address, const char *host)
 Translates a hostname to an IP address.

Protected Member Functions

virtual int socket_open (void **handle, nsapi_protocol_t proto)=0
 Opens a socket.
virtual int socket_close (void *handle)=0
 Close the socket.
virtual int socket_bind (void *handle, const SocketAddress &address)=0
 Bind a specific address to a socket.
virtual int socket_listen (void *handle, int backlog)=0
 Listen for connections on a TCP socket.
virtual int socket_connect (void *handle, const SocketAddress &address)=0
 Connects TCP socket to a remote host.
virtual int socket_accept (void **handle, void *server)=0
 Accepts a connection on a TCP socket.
virtual int socket_send (void *handle, const void *data, unsigned size)=0
 Send data over a TCP socket.
virtual int socket_recv (void *handle, void *data, unsigned size)=0
 Receive data over a TCP socket.
virtual int socket_sendto (void *handle, const SocketAddress &address, const void *data, unsigned size)=0
 Send a packet over a UDP socket.
virtual int socket_recvfrom (void *handle, SocketAddress *address, void *buffer, unsigned size)=0
 Receive a packet over a UDP socket.
virtual void socket_attach (void *handle, void(*callback)(void *), void *data)=0
 Register a callback on state change of the socket.

Friends

class Socket
class UDPSocket
class TCPSocket
class TCPServer

Detailed Description

NetworkStack class.

Common interface that is shared between hardware that can connect to a network over IP. By implementing the NetworkStack, a network stack can be used as a target for instantiating network sockets.

Definition at line 89 of file NetworkStack.h.


Member Function Documentation

virtual const char* get_ip_address (  ) [pure virtual]

Get the local IP address.

Returns:
Null-terminated representation of the local IP address or null if not yet connected
int gethostbyname ( SocketAddress address,
const char *  host 
) [virtual]

Translates a hostname to an IP address.

The hostname may be either a domain name or an IP address. If the hostname is an IP address, no network transactions will be performed.

If no stack-specific DNS resolution is provided, the hostname will be resolve using a UDP socket on the stack.

Parameters:
addressDestination for the host SocketAddress
hostHostname to resolve
Returns:
0 on success, negative error code on failure

Definition at line 20 of file NetworkStack.cpp.

virtual int socket_accept ( void **  handle,
void *  server 
) [protected, pure virtual]

Accepts a connection on a TCP socket.

The server socket must be bound and set to listen for connections. On a new connection, creates a network socket and stores it in the specified handle. The handle must be passed to following calls on the socket.

A stack may have a finite number of sockets, in this case NSAPI_ERROR_NO_SOCKET is returned if no socket is available.

This call is non-blocking. If accept would block, NSAPI_ERROR_WOULD_BLOCK is returned immediately.

Parameters:
handleDestination for a handle to the newly created sockey
serverSocket handle to server to accept from
Returns:
0 on success, negative error code on failure
virtual void socket_attach ( void *  handle,
void(*)(void *)  callback,
void *  data 
) [protected, pure virtual]

Register a callback on state change of the socket.

The specified callback will be called on state changes such as when the socket can recv/send/accept successfully and on when an error occurs. The callback may also be called spuriously without reason.

The callback may be called in an interrupt context and should not perform expensive operations such as recv/send calls.

Parameters:
handleSocket handle
callbackFunction to call on state change
dataArgument to pass to callback
virtual int socket_bind ( void *  handle,
const SocketAddress address 
) [protected, pure virtual]

Bind a specific address to a socket.

Binding a socket specifies the address and port on which to recieve data. If the IP address is zeroed, only the port is bound.

Parameters:
handleSocket handle
addressLocal address to bind
Returns:
0 on success, negative error code on failure.
virtual int socket_close ( void *  handle ) [protected, pure virtual]

Close the socket.

Closes any open connection and deallocates any memory associated with the socket.

Parameters:
handleSocket handle
Returns:
0 on success, negative error code on failure
virtual int socket_connect ( void *  handle,
const SocketAddress address 
) [protected, pure virtual]

Connects TCP socket to a remote host.

Initiates a connection to a remote server specified by the indicated address.

Parameters:
handleSocket handle
addressThe SocketAddress of the remote host
Returns:
0 on success, negative error code on failure
virtual int socket_listen ( void *  handle,
int  backlog 
) [protected, pure virtual]

Listen for connections on a TCP socket.

Marks the socket as a passive socket that can be used to accept incoming connections.

Parameters:
handleSocket handle
backlogNumber of pending connections that can be queued simultaneously
Returns:
0 on success, negative error code on failure
virtual int socket_open ( void **  handle,
nsapi_protocol_t  proto 
) [protected, pure virtual]

Opens a socket.

Creates a network socket and stores it in the specified handle. The handle must be passed to following calls on the socket.

A stack may have a finite number of sockets, in this case NSAPI_ERROR_NO_SOCKET is returned if no socket is available.

Parameters:
handleDestination for the handle to a newly created socket
protoProtocol of socket to open, NSAPI_TCP or NSAPI_UDP
Returns:
0 on success, negative error code on failure
virtual int socket_recv ( void *  handle,
void *  data,
unsigned  size 
) [protected, pure virtual]

Receive data over a TCP socket.

The socket must be connected to a remote host. Returns the number of bytes received into the buffer.

This call is non-blocking. If recv would block, NSAPI_ERROR_WOULD_BLOCK is returned immediately.

Parameters:
handleSocket handle
dataDestination buffer for data received from the host
sizeSize of the buffer in bytes
Returns:
Number of received bytes on success, negative error code on failure
virtual int socket_recvfrom ( void *  handle,
SocketAddress address,
void *  buffer,
unsigned  size 
) [protected, pure virtual]

Receive a packet over a UDP socket.

Receives data and stores the source address in address if address is not NULL. Returns the number of bytes received into the buffer.

This call is non-blocking. If recvfrom would block, NSAPI_ERROR_WOULD_BLOCK is returned immediately.

Parameters:
handleSocket handle
addressDestination for the source address or NULL
dataDestination buffer for data received from the host
sizeSize of the buffer in bytes
Returns:
Number of received bytes on success, negative error code on failure
virtual int socket_send ( void *  handle,
const void *  data,
unsigned  size 
) [protected, pure virtual]

Send data over a TCP socket.

The socket must be connected to a remote host. Returns the number of bytes sent from the buffer.

This call is non-blocking. If send would block, NSAPI_ERROR_WOULD_BLOCK is returned immediately.

Parameters:
handleSocket handle
dataBuffer of data to send to the host
sizeSize of the buffer in bytes
Returns:
Number of sent bytes on success, negative error code on failure
virtual int socket_sendto ( void *  handle,
const SocketAddress address,
const void *  data,
unsigned  size 
) [protected, pure virtual]

Send a packet over a UDP socket.

Sends data to the specified address. Returns the number of bytes sent from the buffer.

This call is non-blocking. If sendto would block, NSAPI_ERROR_WOULD_BLOCK is returned immediately.

Parameters:
handleSocket handle
addressThe SocketAddress of the remote host
dataBuffer of data to send to the host
sizeSize of the buffer in bytes
Returns:
Number of sent bytes on success, negative error code on failure