ftcd_comm_socket.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
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 __FTCD_COMM_SOCKET_H__
00018 #define __FTCD_COMM_SOCKET_H__
00019 
00020 #include "ftcd_comm_base.h"
00021 #include "pal.h"
00022 #include <inttypes.h>
00023 
00024 #define INFINITE_SOCKET_TIMEOUT -1
00025 
00026 /**
00027 * List of supported networks domains. Current supported domain is ipv4 only.
00028 */
00029 typedef enum {
00030     FTCD_AF_UNSPEC = 0,//!< Unspecified IP protocol.
00031     FTCD_IPV4 = 2,     //!< Internet IP Protocol.
00032 } ftcd_socket_domain_e;
00033 
00034 /**
00035 * Type for sockets.
00036 */
00037 typedef void* palSocket_t ;
00038 /**
00039 * Structure for Ethernet interface info.
00040 */
00041 struct palNetInterfaceInfo ;
00042 /**
00043 * Class for Ethernet interface.
00044 */
00045 class EthernetInterface;
00046 
00047 /** FtcdCommSocket implements the logic of listening for TCP connections and
00048 *  process incoming messages from the Factory Tool.
00049 */
00050 class FtcdCommSocket : public FtcdCommBase {
00051 
00052 public:
00053 
00054     /**
00055     * The Socket Constructor
00056     * Initializes private variables and sets network interface handler, IP and port number.
00057     * If port_num is 0, then random port will be generated.
00058     */
00059     FtcdCommSocket(const void *interfaceHandler, ftcd_socket_domain_e domain, const uint16_t port_num, ftcd_comm_network_endianness_e network_endianness = FTCD_COMM_NET_ENDIANNESS_BIG, int32_t timeout = INFINITE_SOCKET_TIMEOUT);
00060 
00061     /**
00062     * The Socket Constructor
00063     * Initializes private variables and sets network interface handler, IP and port number.
00064     * If port_num is 0, then random port will be generated.
00065     */
00066     FtcdCommSocket(const void *interfaceHandler, ftcd_socket_domain_e domain, const uint16_t port_num, ftcd_comm_network_endianness_e network_endianness, const uint8_t *header_token, bool use_signature, int32_t timeout = INFINITE_SOCKET_TIMEOUT);
00067 
00068     /**
00069     * The Socket Destructor
00070     * Closes opened resources and frees allocated memory.
00071     */
00072     virtual ~FtcdCommSocket();
00073 
00074     /**
00075     * Initializes Network interface and prints its address.
00076     */
00077     virtual bool init(void);
00078 
00079     /**
00080     * Closes opened sockets
00081     */
00082     virtual void finish(void);
00083 
00084     /** Wait and read complete message from the communication line.
00085     * The method waits in blocking mode for new message,
00086     * allocate and read the message,
00087     * and sets message_out and message_size_out
00088     *
00089     * @param message_out The message allocated and read from the communication line
00090     * @param message_size_out The message size in bytes
00091     *
00092     * @returns
00093     *     FTCD_COMM_STATUS_SUCCESS on success, otherwise appropriate error from  ftcd_comm_status_e
00094     */
00095     virtual ftcd_comm_status_e wait_for_message(uint8_t **message_out, uint32_t *message_size_out);
00096 
00097     /** Detects the message token from the communication line medium.
00098     *
00099     * @returns
00100     *     true, if token detected and false otherwise
00101     */
00102     virtual ftcd_comm_status_e is_token_detected(void);
00103 
00104     /** Reads the message size in bytes from the communication line medium.
00105     * This is the amount of bytes needed to allocate for the upcoming message bytes.
00106     *
00107     * @returns
00108     *     The message size in bytes in case of success, zero bytes otherwise.
00109     */
00110     virtual uint32_t read_message_size(void);
00111 
00112     /** Reads the message size in bytes from the communication line medium.
00113     * This is the amount of bytes needed to allocate for the upcoming message bytes.
00114     *
00115     * @param message_out The buffer to read into and return to the caller.
00116     * @param message_size The message size in bytes.
00117     *
00118     * @returns
00119     *     true upon success, false otherwise
00120     */
00121     virtual bool read_message(uint8_t *message_out, size_t message_size);
00122 
00123     /** Reads the message size in bytes from the communication line medium.
00124     * This is the amount of bytes needed to allocate for the upcoming message bytes.
00125     *
00126     * @param sig The buffer to read into and return to the caller.
00127     * @param sig_size The sig buffer size in bytes.
00128     *
00129     * @returns
00130     *     The message size in bytes in case of success, zero bytes otherwise.
00131     */
00132     virtual bool read_message_signature(uint8_t *sig, size_t sig_size);
00133 
00134     /** Writes the given data to the communication line medium.
00135     *
00136     * @param data The bytes to send through the communication line medium
00137     * @param data_size The data size in bytes
00138     *
00139     * @returns
00140     *     true upon success, false otherwise
00141     */
00142     virtual bool send(const uint8_t *data, uint32_t data_size);
00143 
00144 private:
00145 
00146     const void *_interface_handler;
00147     palSocket_t _server_socket;
00148     palSocket_t _client_socket;
00149     palNetInterfaceInfo  *_net_interface_info;
00150     uint16_t _port;
00151     ftcd_socket_domain_e _current_domain_type;
00152     ftcd_socket_domain_e _required_domain_type;
00153     uint32_t _interface_index;
00154     int32_t _rcv_timeout;
00155 
00156     /** Starts listening for incoming TCP socket connection
00157     *   A single connection allowed at a time
00158     *
00159     *   @returns
00160     *       true, if listen to the socket succeeded.
00161     */
00162     bool _listen(void);
00163 
00164     /**Reads a requested amount of bytes from a TCP socket
00165     *
00166     * @param data_out Pre-allocated buffer to be filled
00167     * @param data_out_size Buffer length in bytes
00168     *
00169     * @returns
00170     *    0, if the number of bytes read from the socket were exactly bufferOutSize, error status otherwise.
00171     */
00172     ftcd_comm_status_e _read_from_socket(void *data_out, int data_out_size);
00173 
00174 };
00175 
00176 
00177 #endif //__FTCD_COMM_SOCKET_H__