Socket.h

00001 /*
00002  * PackageLicenseDeclared: Apache-2.0
00003  * Copyright (c) 2015 ARM Limited
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef __MBED_NET_SOCKETS_V0_SOCKET_H__
00018 #define __MBED_NET_SOCKETS_V0_SOCKET_H__
00019 
00020 
00021 #include <stddef.h>
00022 #include <stdint.h>
00023 #include "mbed.h"
00024 #include "FunctionPointer.h"
00025 #include "CThunk.h"
00026 #include "sal/socket_types.h"
00027 #include "SocketAddr.h"
00028 
00029 namespace mbed {
00030 namespace Sockets {
00031 namespace v0 {
00032 
00033 /**
00034  * \brief Socket implements most of the interfaces required for sockets.
00035  * Socket is a pure virtual class; it should never be instantiated directly, but it provides
00036  * common functionality for derived classes.
00037  */
00038 class Socket {
00039 public:
00040     typedef FunctionPointer3<void, Socket *, struct socket_addr, const char *> DNSHandler_t;
00041     typedef FunctionPointer2<void, Socket *, socket_error_t> ErrorHandler_t;
00042     typedef FunctionPointer1<void, Socket *> ReadableHandler_t;
00043     typedef FunctionPointer2<void, Socket *, uint16_t> SentHandler_t;
00044 protected:
00045     /**
00046      * Socket constructor
00047      * Initializes the Socket object.  Initializes the underlying struct socket.  Does not instantiate
00048      * an underlying network stack socket.
00049      * Since it is somewhat awkward to provide the network stack, a future change will provide
00050      * a way to pass the network interface to the socket constructor, which will extract the stack from
00051      * the interface.
00052      * @param[in] stack The network stack to use for this socket.
00053      */
00054     Socket(const socket_stack_t stack);
00055     /**
00056      * Socket destructor
00057      * Frees the underlying socket implementation.
00058      */
00059     virtual ~Socket();
00060 public:
00061     /**
00062      * Start the process of resolving a domain name.
00063      * If the input is a text IP address, an event is queued immediately; otherwise, onDNS is
00064      * queued as soon as DNS is resolved.
00065      * The socket must have been opened before resolve is called
00066      * @param[in] address The domain name to resolve
00067      * @param[in] onDNS The handler to call when the name is resolved
00068      * @return SOCKET_ERROR_NONE on success, or an error code on failure
00069      */
00070     virtual socket_error_t resolve(const char* address, const DNSHandler_t &onDNS);
00071     /**
00072      * Open the socket.
00073      * Instantiates and initializes the underlying socket. Receive is started immediately after
00074      * the socket is opened.
00075      * @param[in] af Address family (SOCKET_AF_INET4 or SOCKET_AF_INET6), currently only IPv4 is supported
00076      * @param[in] pf Protocol family (SOCKET_DGRAM or SOCKET_STREAM)
00077      * @return SOCKET_ERROR_NONE on success, or an error code on failure
00078      */
00079     virtual socket_error_t open(const socket_address_family_t af, const socket_proto_family_t pf);
00080     /**
00081      * Binds the socket's local address and IP.
00082      * 0.0.0.0 is accepted as a local address if only the port is meant to be bound.
00083      * The behaviour of bind("0.0.0.0",...) is undefined where two or more stacks are in use.
00084      *
00085      * @param[in] address The string representation of the address to bind
00086      * @param[in] port The local port to bind
00087      * @return SOCKET_ERROR_NONE on success, or an error code on failure
00088      */
00089     virtual socket_error_t bind(const char *address, const uint16_t port);
00090     /**
00091      * bind(const SocketAddr *, const uint16_t) is the same as bind(const char *, const uint16_t),
00092      * except that the address passed in is a SocketAddr.
00093      * @param[in] address The address to bind
00094      * @param[in] port The local port to bind
00095      * @return SOCKET_ERROR_NONE on success, or an error code on failure
00096      */
00097     virtual socket_error_t bind(const SocketAddr *address, const uint16_t port);
00098     /**
00099      * Set the error handler.
00100      * Errors are ignored if onError is not set.
00101      * @param[in] onError
00102      */
00103     virtual void setOnError(const ErrorHandler_t &onError);
00104     /**
00105      * Set the received data handler
00106      * Received data is queued until it is read using recv or recv_from.
00107      * @param[in] onReadable the handler to use for receive events
00108      */
00109     virtual void setOnReadable(const ReadableHandler_t &onReadable);
00110     /**
00111      * Receive a message
00112      * @param[out] buf The buffer to fill
00113      * @param[in,out] len A pointer to the size of the receive buffer.  Sets the maximum number of bytes
00114      * to read but is updated with the actual number of bytes copied on success.  len is not changed on
00115      * failure
00116      * @return SOCKET_ERROR_NONE on success, or an error code on failure
00117      */
00118     virtual socket_error_t recv(void * buf, size_t *len);
00119     /**
00120      * Receive a message with the sender address and port
00121      * This API is not valid for SOCK_STREAM
00122      * @param[out] buf The buffer to fill
00123      * @param[in,out] len A pointer to the size of the receive buffer.  Sets the maximum number of bytes
00124      * to read but is updated with the actual number of bytes copied on success.  len is not changed on
00125      * failure
00126      * @param[out] remote_addr Pointer to an address structure to fill with the sender address
00127      * @param[out] remote_port Pointer to a uint16_t to fill with the sender port
00128      * @return SOCKET_ERROR_NONE on success, or an error code on failure
00129      */
00130     virtual socket_error_t recv_from(void * buf, size_t *len, SocketAddr *remote_addr, uint16_t *remote_port);
00131     /**
00132      * Set the onSent handler.
00133      * The exact moment this handler is called varies from implementation to implementation.
00134      * On LwIP, onSent is called when the remote host ACK's data in TCP sockets, or when the message enters
00135      * the network stack in UDP sockets.
00136      * @param[in] onSent The handler to call when a send completes
00137      */
00138     virtual void setOnSent(const SentHandler_t &onSent);
00139     /**
00140      * Send a message
00141      * Sends a message over an open connection.  This call is valid for UDP sockets, provided that connect()
00142      * has been called.
00143      * @param[in] buf The payload to send
00144      * @param[in] len The size of the payload
00145      * @return SOCKET_ERROR_NONE on success, or an error code on failure
00146      */
00147     virtual socket_error_t send(const void * buf, const size_t len);
00148     /**
00149      * Send a message to a specific address and port
00150      * This API is not valid for SOCK_STREAM
00151      * @param[in] buf The payload to send
00152      * @param[in] len The size of the payload
00153      * @param[in] address The address to send to
00154      * @param[in] port The remote port to send to
00155      * @return SOCKET_ERROR_NONE on success, or an error code on failure
00156      */
00157     virtual socket_error_t send_to(const void * buf, const size_t len, const SocketAddr *remote_addr, uint16_t remote_port);
00158     /**
00159      * Shuts down a socket.
00160      * Sending and receiving are no longer possible after close() is called.
00161      * The socket is not deallocated on close.  A socket must not be reopened, it should be
00162      * destroyed (either with delete, or by going out of scope) after calling close.
00163      * Calling open on a closed socket can result in a memory leak.
00164      * @return SOCKET_ERROR_NONE on success, or an error code on failure
00165      */
00166     virtual socket_error_t close();
00167     /**
00168      * Error checking utility
00169      * Generates an event on error, does nothing on SOCKET_ERROR_NONE
00170      * @param[in] err the error code to check
00171      * @return false if err is SOCKET_ERROR_NONE, true otherwise
00172      */
00173     virtual bool error_check(socket_error_t err);
00174 
00175     /**
00176      * Checks the socket status to determine whether it is still connected.
00177      * @return true if the socket is connected, false if it is not
00178      */
00179     virtual bool isConnected() const;
00180 
00181     /**
00182      * Get the local address of the socket if bound.
00183      * There are several failing conditions for this method:
00184      * 1. If the socket has not been opened, returns SOCKET_ERROR_NULL_PTR
00185      * 2. If the socket has not been bound, returns SOCKET_ERROR_NOT_BOUND
00186      * 3. If addr is NULL, returns SOCKET_ERROR_NULL_PTR
00187      *
00188      * Otherwise, populates the SocketAddr object with the local address
00189      *
00190      * @param[out] addr a pointer to a SocketAddr object
00191      * @return SOCKET_ERROR_NONE on success, or an error code on failure (see description)
00192      */
00193     virtual socket_error_t getLocalAddr(SocketAddr *addr) const;
00194 
00195     /**
00196      * Get the local port of the socket if bound.
00197      * There are several failing conditions for this method:
00198      * 1. If the socket has not been opened, returns SOCKET_ERROR_NULL_PTR
00199      * 2. If the socket has not been bound, returns SOCKET_ERROR_NOT_BOUND
00200      * 3. If port is NULL, returns SOCKET_ERROR_NULL_PTR
00201      *
00202      * Otherwise, populates the uint16_t object with the local port
00203      *
00204      * @param[out] port a pointer to a uint16_t
00205      * @return SOCKET_ERROR_NONE on success, or an error code on failure (see description)
00206      */
00207     virtual socket_error_t getLocalPort(uint16_t *port) const;
00208 
00209     /**
00210      * Get the remote address of the socket if connected.
00211      * There are several failing conditions for this method:
00212      * 1. If the socket has not been opened, returns SOCKET_ERROR_NULL_PTR
00213      * 2. If the socket has not been connected, returns SOCKET_ERROR_NO_CONNECTION
00214      * 3. If addr is NULL, returns SOCKET_ERROR_NULL_PTR
00215      *
00216      * Otherwise, populates the SocketAddr object with the remote address
00217      *
00218      * @param[out] addr a pointer to a SocketAddr object
00219      * @return SOCKET_ERROR_NONE on success, or an error code on failure (see description)
00220      */
00221     virtual socket_error_t getRemoteAddr(SocketAddr *addr) const;
00222     /**
00223      * Get the remote port of the socket if connected.
00224      * There are several failing conditions for this method:
00225      * 1. If the socket has not been opened, returns SOCKET_ERROR_NULL_PTR
00226      * 2. If the socket has not been connected, returns SOCKET_ERROR_NO_CONNECTION
00227      * 3. If port is NULL, returns SOCKET_ERROR_NULL_PTR
00228      *
00229      * Otherwise, populates the uint16_t object with the remote port
00230      *
00231      * @param[out] port a pointer to a uint16_t
00232      * @return SOCKET_ERROR_NONE on success, or an error code on failure (see description)
00233      */
00234     virtual socket_error_t getRemotePort(uint16_t *port) const;
00235 
00236 #if 0 // not implemented yet
00237     static long ntohl(long);
00238     static short ntohs(short);
00239     static long long ntohll(long long);
00240 #endif
00241 
00242 protected:
00243     /**
00244      * The internal event handler
00245      * @param[in] ev The event to handle
00246      */
00247     virtual void _eventHandler(struct socket_event *ev);
00248 
00249 protected:
00250     DNSHandler_t      _onDNS;
00251     ErrorHandler_t    _onError;
00252     ReadableHandler_t _onReadable;
00253     SentHandler_t     _onSent;
00254 
00255     CThunk<Socket>  _irq;
00256     struct socket _socket;
00257 private:
00258     socket_event_t *_event;
00259     /**
00260      * Internal event handler.
00261      * @param[in] arg
00262      */
00263     void _nvEventHandler(void * arg);
00264 };
00265 } // namespace v0
00266 } // namespace Sockets
00267 } // namespace mbed
00268 #endif // __MBED_NET_SOCKETS_V0_SOCKET_H__