pal_plat_network.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 
00018 #ifndef _PAL_PLAT_SOCKET_H
00019 #define _PAL_PLAT_SOCKET_H
00020 
00021 #include "pal.h"
00022 #include "pal_network.h"
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 /*! \file pal_plat_network.h
00029  *  \brief PAL network - platform.
00030  *   This file contains the network APIs that need to be implemented in the platform layer.
00031  *
00032  * **PAL network socket API** /n
00033  * PAL network socket configuration options:
00034  * - define PAL_NET_TCP_AND_TLS_SUPPORT if TCP is supported by the platform and is required.
00035  * - define PAL_NET_ASYNCHRONOUS_SOCKET_API if asynchronous socket API is supported by the platform. Currently **mandatory**.
00036  * - define PAL_NET_DNS_SUPPORT if DNS name resolution is supported.
00037  */
00038 
00039 /*! \brief Initialize sockets.
00040  *
00041  * Must be called before other socket functions. By default, is called from PAL init.
00042  * @param[in] context Optional context. If not available or applicable, use NULL.
00043  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00044  */
00045 palStatus_t pal_plat_socketsInit(void* context);
00046 
00047 /*! \brief Register a network interface for use with PAL sockets.
00048  *
00049  * Must be called before other socket functions. Most APIs will not work before an interface is added.
00050  * @param[in] networkInterfaceContext The context of the network interface to be added. This is OS-specific. \n
00051               In mbed OS, this is the NetworkInterface object pointer for the network adapter and assumes a connect has already been called on this. \n
00052               If not available, use NULL. This is not required on some OSs.
00053  * @param[out] interfaceIndex Contains the index assigned to the interface if it has been assigned successfully. This index can be used when creating a socket to bind the socket to the interface.
00054  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00055  */
00056 palStatus_t pal_plat_registerNetworkInterface(void* networkInterfaceContext, uint32_t* interfaceIndex);
00057 
00058 /*! Unregister a network interface.
00059 * @param interfaceIndex Index of the network interface to be removed.
00060 \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00061 */
00062 palStatus_t pal_plat_unregisterNetworkInterface (uint32_t interfaceIndex);
00063 
00064 /*! \brief Socket termination.
00065  *
00066  * This can be called when sockets are no longer needed, to free socket resources.
00067  * @param[in] context Optional context. If not available, use NULL.
00068  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00069 */
00070 palStatus_t pal_plat_socketsTerminate(void* context);
00071 
00072 /*! \brief Get a network socket.
00073  * @param[in] domain The domain of the created socket. See `palSocketDomain_t` for supported types.
00074  * @param[in] type The type of the created socket. See `palSocketType_t` for supported types.
00075  * @param[in] nonBlockingSocket If true, the socket is non-blocking.
00076  * @param[in] interfaceNum The number of the network interface used for this socket. Select `PAL_NET_DEFAULT_INTERFACE` for the default interface.
00077  * @param[out] socket The socket is returned through this output parameter.
00078  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00079  */
00080 palStatus_t pal_plat_socket(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palSocket_t* socket);
00081 
00082 /*! \brief Set options for a network socket.
00083  *
00084  * See `palSocketOptionName_t` for supported options.
00085  * @param[in] socket The socket to configure.
00086  * @param[in] optionName The name of the option to be set. See enum `palSocketOptionName_t` for supported types.
00087  * @param[in] optionValue The buffer holding the value to set for the given option.
00088  * @param[in] optionLength The size of the buffer provided for `optionValue` in bytes.
00089  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00090  */
00091 palStatus_t pal_plat_setSocketOptions(palSocket_t socket, int optionName, const void* optionValue, palSocketLength_t optionLength);
00092 
00093 /*! \brief Check if a socket is non-blocking.
00094  * @param[in] socket The socket for which to check non-blocking status.
00095  * @param[out] isNonBlocking The non-blocking status for the socket. Is `true` if non-blocking, otherwise `false`.
00096  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00097  */
00098 palStatus_t pal_plat_isNonBlocking(palSocket_t socket, bool* isNonBlocking);
00099 
00100 /*! \brief Bind a socket to a local address.
00101  * @param[in] socket The socket to bind.
00102  * @param[in] myAddress The address to bind to.
00103  * @param[in] addressLength The length of the address passed in `myAddress`.
00104  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00105  */
00106 palStatus_t pal_plat_bind(palSocket_t socket, palSocketAddress_t* myAddress, palSocketLength_t addressLength);
00107 
00108 /*! \brief Receive a payload from a socket.
00109  * @param[in] socket The socket to receive from. The socket passed to this function should be of type `PAL_SOCK_DGRAM`, unless your specific implementation supports other types as well.
00110  * @param[out] buffer The buffer for the payload data.
00111  * @param[in] length The length of the buffer for the payload data in bytes.
00112  * @param[out] from The address that sent the payload. This value is optional, pass NULL when not used.
00113  * @param[in, out] fromLength The length of the `from` address. When completed, this contains the amount of data actually written to the `from` address. This value is optional, pass NULL when not used.
00114  * @param[out] bytesReceived The actual amount of payload data received in the buffer.
00115  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00116  */
00117 palStatus_t pal_plat_receiveFrom(palSocket_t socket, void* buffer, size_t length, palSocketAddress_t* from, palSocketLength_t* fromLength, size_t* bytesReceived);
00118 
00119 /*! \brief Send a payload to an address using a specific socket.
00120  * @param[in] socket The socket to use for sending the payload. The socket passed to this function should be of type `PAL_SOCK_DGRAM`, unless your specific implementation supports other types as well.
00121  * @param[in] buffer The buffer for the payload data.
00122  * @param[in] length The length of the buffer for the payload data.
00123  * @param[in] to The address to which the payload should be sent.
00124  * @param[in] toLength The length of the `to` address.
00125  * @param[out] bytesSent The actual amount of payload data sent.
00126  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00127  */
00128 palStatus_t pal_plat_sendTo(palSocket_t socket, const void* buffer, size_t length, const palSocketAddress_t* to, palSocketLength_t toLength, size_t* bytesSent);
00129 
00130 /*! \brief Close a network socket.
00131  * \note The function recieves `palSocket_t*` and not `palSocket_t` so that it can zero the socket to avoid re-use.
00132  * @param[in,out] socket Pointer to the socket to release and zero.
00133  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00134  */
00135 palStatus_t pal_plat_close(palSocket_t* socket);
00136 
00137 /*! \brief Get the number of current network interfaces.
00138  *
00139  * The function counts interfaces that have been successfully registered.
00140  * @param[out] numInterfaces The number of interfaces after a successful call.
00141  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00142  */
00143 palStatus_t pal_plat_getNumberOfNetInterfaces(uint32_t* numInterfaces);
00144 
00145 /*! \brief Get information regarding a socket at a specific interface number.
00146  * @param[in] interfaceNum The number of the interface to get information from.
00147  * @param[out] interfaceInfo The information for the given interface number.
00148  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00149  */
00150 palStatus_t pal_plat_getNetInterfaceInfo(uint32_t interfaceNum, palNetInterfaceInfo_t* interfaceInfo);
00151 
00152 #if PAL_NET_TCP_AND_TLS_SUPPORT // The functionality below is supported only if TCP is supported.
00153 
00154 /*! \brief Use a socket to listen to incoming connections.
00155  *
00156  * You may also limit the queue of incoming connections.
00157  * @param[in] socket The socket to listen to. The docket passed to this function should be of type `PAL_SOCK_STREAM_SERVER`, unless your specific implementation supports other types as well.
00158  * @param[in] backlog The number of pending connections that can be saved for the socket.
00159  * \return PAL_SUCCESS (0) in case of success. A specific negative error code in case of failure.
00160  */
00161 palStatus_t pal_plat_listen(palSocket_t socket, int backlog);
00162 
00163 /*! \brief Accept a connection on a socket.
00164  * @param[in] socket The socket on which to accept the connection. The socket needs to be created and bound, and `pal_plat_listen` must have been called on it. The socket passed to this function should be of type `PAL_SOCK_STREAM_SERVER`, unless your specific implementation supports other types as well.
00165  * @param[out] address The source address of the incoming connection.
00166  * @param[in, out] addressLen The length of the address field on input, the length of the data returned on output.
00167  * @param[out] acceptedSocket The socket of the accepted connection is returned if the connection is accepted successfully.
00168  * \return PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00169  */
00170 palStatus_t pal_plat_accept(palSocket_t socket, palSocketAddress_t* address, palSocketLength_t* addressLen, palSocket_t* acceptedSocket);
00171 
00172 /*! \brief Open a connection from a socket to a specific address.
00173  * @param[in] socket The socket to use for the connection to the given address. The socket passed to this function should be of type `PAL_SOCK_STREAM`, unless your specific implementation supports other types as well.
00174  * @param[in] address The destination address of the connection.
00175  * @param[in] addressLen The length of the address field.
00176  * \return PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00177  */
00178 palStatus_t pal_plat_connect(palSocket_t socket, const palSocketAddress_t* address, palSocketLength_t addressLen);
00179 
00180 /*! \brief Receive data from a connected socket.
00181  * @param[in] socket The connected socket on which to receive data. Sockets passed to this function should be of type PAL_SOCK_STREAM, unless your specific implementation supports other types as well.
00182  * @param[out] buf The output buffer for the message data.
00183  * @param[in] len The length of the input data buffer in bytes.
00184  * @param[out] recievedDataSize The length of the data actually received in bytes.
00185  * \return PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00186  */
00187 palStatus_t pal_plat_recv(palSocket_t socket, void* buf, size_t len, size_t* recievedDataSize);
00188 
00189 /*! \brief Send a buffer via a specific connected socket.
00190  * @param[in] socket The connected socket on which to send data. The socket passed to this function should be of type `PAL_SOCK_STREAM`, unless your specific implementation supports other types as well.
00191  * @param[in] buf The output buffer for the message data.
00192  * @param[in] len The length of the output data buffer in bytes.
00193  * @param[out] sentDataSize The length of the data sent in bytes.
00194  * \return PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00195  */
00196 palStatus_t pal_plat_send(palSocket_t socket, const void* buf, size_t len, size_t* sentDataSize);
00197 
00198 #endif //PAL_NET_TCP_AND_TLS_SUPPORT
00199 
00200 #if PAL_NET_ASYNCHRONOUS_SOCKET_API
00201 
00202 /*! \brief Get an asynchronous network socket.
00203  * @param[in] domain The domain of the created socket. See enum `palSocketDomain_t` for supported types.
00204  * @param[in] type The type of the created socket. See enum `palSocketType_t` for supported types.
00205  * @param[in] callback A callback function that is called when any supported event takes place in the given asynchronous socket.
00206  * @param[in] callbackArgument the argument with which the specified callback will be called when any supported event takes place in the given asynchronous socket.
00207  * @param[out] socket This output parameter returns the socket.
00208  * \return PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00209  */
00210 palStatus_t pal_plat_asynchronousSocket(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, void* callbackArgument , palSocket_t* socket);
00211 
00212 #endif
00213 
00214 #if PAL_NET_DNS_SUPPORT
00215 #if (PAL_DNS_API_VERSION == 0) || (PAL_DNS_API_VERSION == 1)
00216 
00217 /*! \brief This function translates a URL to a `palSocketAddress_t` that can be used with PAL sockets.
00218  * @param[in] url The URL to be translated to a `palSocketAddress_t`.
00219  * @param[out] address The address for the output of the translation.
00220  * @param[out] addressLength The length of the output address.
00221  */
00222 palStatus_t pal_plat_getAddressInfo(const char* url, palSocketAddress_t* address, palSocketLength_t* addressLength);
00223 
00224 #elif (PAL_DNS_API_VERSION == 2)
00225 
00226 /*! \brief This function translates a URL to a `palSocketAddress_t` that can be used with PAL sockets.
00227  * @param[in] info address of `pal_asyncAddressInfo_t`.
00228  */
00229 palStatus_t pal_plat_getAddressInfoAsync(pal_asyncAddressInfo_t* info);
00230 
00231 /*! \brief This function is cancelation for `pal_plat_getAddressInfoAsync()`.
00232  * @param[in] queryHandle ID of ongoing DNS query.
00233  */
00234 palStatus_t pal_plat_cancelAddressInfoAsync(palDNSQuery_t queryHandle);
00235 #else
00236     #error "Please specify the platform PAL_DNS_API_VERSION 0, 1, or 2."
00237 #endif //  PAL_DNS_API_VERSION
00238 
00239 #endif // PAL_NET_DNS_SUPPORT
00240 
00241 
00242 #ifdef __cplusplus
00243 }
00244 #endif
00245 #endif //_PAL_PLAT_SOCKET_H