Pierre-Marie Ancèle
test
Diff: aws-iot/include/network_interface.h
- Revision:
- 0:cd5404401c2f
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/aws-iot/include/network_interface.h Wed Apr 12 14:07:09 2017 +0200
@@ -0,0 +1,167 @@
+/*
+ * Copyright 2010-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ * http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+/**
+ * @file network_interface.h
+ * @brief Network interface definition for MQTT client.
+ *
+ * Defines an interface to the TLS layer to be used by the MQTT client.
+ * Starting point for porting the SDK to the networking layer of a new platform.
+ */
+
+#ifndef __NETWORK_INTERFACE_H_
+#define __NETWORK_INTERFACE_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <aws_iot_error.h>
+#include "timer_interface.h"
+#include "network_platform.h"
+
+/**
+ * @brief Network Type
+ *
+ * Defines a type for the network struct. See structure definition below.
+ */
+typedef struct Network Network;
+
+/**
+ * @brief TLS Connection Parameters
+ *
+ * Defines a type containing TLS specific parameters to be passed down to the
+ * TLS networking layer to create a TLS secured socket.
+ */
+typedef struct {
+ char *pRootCALocation; ///< Pointer to string containing the filename (including path) of the root CA file.
+ char *pDeviceCertLocation; ///< Pointer to string containing the filename (including path) of the device certificate.
+ char *pDevicePrivateKeyLocation; ///< Pointer to string containing the filename (including path) of the device private key file.
+ char *pDestinationURL; ///< Pointer to string containing the endpoint of the MQTT service.
+ uint16_t DestinationPort; ///< Integer defining the connection port of the MQTT service.
+ uint32_t timeout_ms; ///< Unsigned integer defining the TLS handshake timeout value in milliseconds.
+ bool ServerVerificationFlag; ///< Boolean. True = perform server certificate hostname validation. False = skip validation \b NOT recommended.
+} TLSConnectParams;
+
+/**
+ * @brief Network Structure
+ *
+ * Structure for defining a network connection.
+ */
+struct Network {
+ IoT_Error_t (*connect)(Network *, TLSConnectParams *);
+
+ IoT_Error_t (*read)(Network *, unsigned char *, size_t, TimerAWS *, size_t *); ///< Function pointer pointing to the network function to read from the network
+ IoT_Error_t (*write)(Network *, unsigned char *, size_t, TimerAWS *, size_t *); ///< Function pointer pointing to the network function to write to the network
+ IoT_Error_t (*disconnect)(Network *); ///< Function pointer pointing to the network function to disconnect from the network
+ IoT_Error_t (*isConnected)(Network *); ///< Function pointer pointing to the network function to check if TLS is connected
+ IoT_Error_t (*destroy)(Network *); ///< Function pointer pointing to the network function to destroy the network object
+
+ TLSConnectParams tlsConnectParams; ///< TLSConnect params structure containing the common connection parameters
+ TLSDataParams tlsDataParams; ///< TLSData params structure containing the connection data parameters that are specific to the library being used
+};
+
+/**
+ * @brief Initialize the TLS implementation
+ *
+ * Perform any initialization required by the TLS layer.
+ * Connects the interface to implementation by setting up
+ * the network layer function pointers to platform implementations.
+ *
+ * @param pNetwork - Pointer to a Network struct defining the network interface.
+ * @param pRootCALocation - Path of the location of the Root CA
+ * @param pDeviceCertLocation - Path to the location of the Device Cert
+ * @param pDevicyPrivateKeyLocation - Path to the location of the device private key file
+ * @param pDestinationURL - The target endpoint to connect to
+ * @param DestinationPort - The port on the target to connect to
+ * @param timeout_ms - The value to use for timeout of operation
+ * @param ServerVerificationFlag - used to decide whether server verification is needed or not
+ *
+ * @return IoT_Error_t - successful initialization or TLS error
+ */
+IoT_Error_t iot_tls_init(Network *pNetwork, char *pRootCALocation, char *pDeviceCertLocation,
+ char *pDevicePrivateKeyLocation, char *pDestinationURL,
+ uint16_t DestinationPort, uint32_t timeout_ms, bool ServerVerificationFlag);
+
+/**
+ * @brief Create a TLS socket and open the connection
+ *
+ * Creates an open socket connection including TLS handshake.
+ *
+ * @param pNetwork - Pointer to a Network struct defining the network interface.
+ * @param TLSParams - TLSConnectParams defines the properties of the TLS connection.
+ * @return IoT_Error_t - successful connection or TLS error
+ */
+IoT_Error_t iot_tls_connect(Network *pNetwork, TLSConnectParams *TLSParams);
+
+/**
+ * @brief Write bytes to the network socket
+ *
+ * @param Network - Pointer to a Network struct defining the network interface.
+ * @param unsigned char pointer - buffer to write to socket
+ * @param integer - number of bytes to write
+ * @param Timer * - operation timer
+ * @return integer - number of bytes written or TLS error
+ * @return IoT_Error_t - successful write or TLS error code
+ */
+IoT_Error_t iot_tls_write(Network *, unsigned char *, size_t, TimerAWS *, size_t *);
+
+/**
+ * @brief Read bytes from the network socket
+ *
+ * @param Network - Pointer to a Network struct defining the network interface.
+ * @param unsigned char pointer - pointer to buffer where read bytes should be copied
+ * @param size_t - number of bytes to read
+ * @param Timer * - operation timer
+ * @param size_t - pointer to store number of bytes read
+ * @return IoT_Error_t - successful read or TLS error code
+ */
+IoT_Error_t iot_tls_read(Network *, unsigned char *, size_t, TimerAWS *, size_t *);
+
+/**
+ * @brief Disconnect from network socket
+ *
+ * @param Network - Pointer to a Network struct defining the network interface.
+ * @return IoT_Error_t - successful read or TLS error code
+ */
+IoT_Error_t iot_tls_disconnect(Network *pNetwork);
+
+/**
+ * @brief Perform any tear-down or cleanup of TLS layer
+ *
+ * Called to cleanup any resources required for the TLS layer.
+ *
+ * @param Network - Pointer to a Network struct defining the network interface
+ * @return IoT_Error_t - successful cleanup or TLS error code
+ */
+IoT_Error_t iot_tls_destroy(Network *pNetwork);
+
+/**
+ * @brief Check if TLS layer is still connected
+ *
+ * Called to check if the TLS layer is still connected or not.
+ *
+ * @param Network - Pointer to a Network struct defining the network interface
+ * @return IoT_Error_t - TLS error code indicating status of network physical layer connection
+ */
+IoT_Error_t iot_tls_is_connected(Network *pNetwork);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif //__NETWORK_INTERFACE_H_