SocketStats.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2018 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef SOCKET_STATS_H
00018 #define SOCKET_STATS_H
00019 
00020 #include "platform/SingletonPtr.h"
00021 #include "platform/PlatformMutex.h"
00022 #include "netsocket/Socket.h"
00023 #include "SocketAddress.h"
00024 #include "hal/ticker_api.h"
00025 
00026 #ifndef MBED_CONF_NSAPI_SOCKET_STATS_MAX_COUNT
00027 #define MBED_CONF_NSAPI_SOCKET_STATS_MAX_COUNT      10
00028 #endif
00029 
00030 /** Enum of socket states
00031   *
00032   * Can be used to specify current state of socket - open, closed, connected or listen.
00033   *
00034   * @enum socket_state
00035   */
00036 typedef enum {
00037     SOCK_CLOSED,                    /**< Socket is closed and does not exist anymore in the system */
00038     SOCK_OPEN,                      /**< Socket is open but not associated to any peer address */
00039     SOCK_CONNECTED,                 /**< Socket is associated to peer address, either by connect() or sendto()/recvfrom() calls */
00040     SOCK_LISTEN,                    /**< Socket is listening for incoming connections */
00041 } socket_state;
00042 
00043 /** Structure to parse socket statistics
00044   */
00045 typedef struct {
00046     Socket *reference_id;           /**< Used for identifying socket */
00047     SocketAddress peer;             /**< Last associated peername of this socket (Destination address) */
00048     socket_state state;             /**< State of this socket */
00049     nsapi_protocol_t proto;         /**< Specifies a protocol used with socket */
00050     size_t sent_bytes;              /**< Data sent through this socket */
00051     size_t recv_bytes;              /**< Data received through this socket */
00052     us_timestamp_t last_change_tick;/**< osKernelGetTick() when state last changed */
00053 } mbed_stats_socket_t;
00054 
00055 /**  SocketStats class
00056  *
00057  *   Class to get the network socket statistics
00058  */
00059 class SocketStats {
00060 public:
00061 
00062 #if !defined(DOXYGEN_ONLY)
00063     /** Create an socket statictics object
00064      *
00065      *  Application users must not create class objects.
00066      *  Entities reporting network statistics create the class object.
00067      *  Application can fetch network statistics using static `mbed_stats_socket_get_each` API
00068      *  without creating an object.
00069      */
00070     SocketStats();
00071     virtual ~SocketStats()
00072     {
00073     }
00074 #endif
00075     /**
00076      *  Fill the passed array of structures with the socket statistics for each created socket.
00077      *
00078      *  @param stats    A pointer to an array of mbed_stats_socket_t structures to fill
00079      *  @param count    The number of mbed_stats_socket_t structures in the provided array
00080      *  @return         The number of mbed_stats_socket_t structures that have been filled.
00081      *                  If the number of sockets on the system is less than or equal to count,
00082      *                  it will equal the number of sockets created (active or closed).
00083      *                  If the number of sockets on the system is greater than count,
00084      *                  it will equal count.
00085      */
00086     static size_t mbed_stats_socket_get_each(mbed_stats_socket_t *stats, size_t count);
00087 
00088 #if !defined(DOXYGEN_ONLY)
00089     /** Add entry of newly created socket in statistics array.
00090      *  API used by socket (TCP or UDP) layers only, not to be used by application.
00091      *
00092      *  @param reference_id   ID to identify socket in data array.
00093      *
00094      *  @Note: The entry in the array is maintained even after the socket is closed.
00095      *         The entry is overwritten for sockets that were closed first, in case
00096      *         the socket creation count exceeds `MBED_CONF_NSAPI_SOCKET_STATS_MAX_COUNT`.
00097      *
00098      */
00099     void stats_new_socket_entry(const Socket *const reference_id);
00100 
00101     /** Updates the state of the socket and records `tick_last_change`.
00102      *  API used by socket (TCP or UDP) layers only, not to be used by application.
00103      *
00104      *  @param reference_id   ID to identify socket in data array.
00105      *  @param state  Parameter to update the current state of the socket.
00106      *
00107      */
00108     void stats_update_socket_state(const Socket *const reference_id, socket_state state);
00109 
00110     /** Update the peer information of the socket.
00111      *  API used by socket (TCP or UDP) layers only, not to be used by application.
00112      *
00113      *  @param reference_id   ID to identify socket in data array.
00114      *  @param peer  Parameter to update destination peer information.
00115      *
00116      */
00117     void stats_update_peer(const Socket *const reference_id, const SocketAddress &peer);
00118 
00119     /** Update socket protocol.
00120      *  API used by socket (TCP or UDP) layers only, not to be used by application.
00121      *
00122      *  @param reference_id   ID to identify socket in data array.
00123      *  @param proto Parameter to update the protocol type of socket.
00124      *
00125      */
00126     void stats_update_proto(const Socket *const reference_id, nsapi_protocol_t proto);
00127 
00128     /** Update bytes sent on socket, which is cumulative count per socket.
00129      *  API used by socket (TCP or UDP) layers only, not to be used by application.
00130      *
00131      *  @param reference_id   ID to identify socket in data array.
00132      *  @param sent_bytes Parameter to append bytes sent over the socket.
00133      *
00134      */
00135     void stats_update_sent_bytes(const Socket *const reference_id, size_t sent_bytes);
00136 
00137     /** Update bytes received on socket, which is cumulative count per socket
00138      *  API used by socket (TCP or UDP) layers only, not to be used by application.
00139      *
00140      *  @param reference_id   ID to identify socket in data array.
00141      *  @param recv_bytes Parameter to append bytes the socket receives.
00142      *
00143      */
00144     void stats_update_recv_bytes(const Socket *const reference_id, size_t recv_bytes);
00145 
00146 #if MBED_CONF_NSAPI_SOCKET_STATS_ENABLED
00147 private:
00148     static mbed_stats_socket_t _stats[MBED_CONF_NSAPI_SOCKET_STATS_MAX_COUNT];
00149     static SingletonPtr<PlatformMutex>  _mutex;
00150     static uint32_t _size;
00151 
00152     /** Internal function to scan the array and get the position of the element in the list.
00153      *
00154      *  @param reference_id   ID to identify the socket in the data array.
00155      *
00156      */
00157     int get_entry_position(const Socket *const reference_id);
00158 #endif
00159 #endif
00160 };
00161 
00162 #endif