pal_plat_network.h

00001 /*
00002 * Copyright (c) 2016 ARM Limited. All rights reserved.
00003 * SPDX-License-Identifier: Apache-2.0
00004 * Licensed under the Apache License, Version 2.0 (the License); you may
00005 * 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, WITHOUT
00012 * 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 //! PAL network socket API
00029 //! PAL network sockets configurations options:
00030 //! define PAL_NET_TCP_AND_TLS_SUPPORT if TCP is supported by the platform and is required.
00031 //! define PAL_NET_ASYNCHRONOUS_SOCKET_API if asynchronous socket API is supported by the platform. Currently MANDATORY.
00032 //! define PAL_NET_DNS_SUPPORT if DNS name resolution is supported.
00033 
00034 /*! Initialize sockets - must be called before other socket functions (is called from PAL init).
00035 * @param[in] context Optional context - if not available/applicable use NULL.
00036 \return The status in the form of palStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00037 */
00038 palStatus_t pal_plat_socketsInit(void* context);
00039 
00040 /*! Register a network interface for use with PAL sockets - must be called before other socket functions - most APIs will not work before a single interface is added.
00041 * @param[in] networkInterfaceContext The context of the network interface to be added (OS specific. In mbed OS, this is the NetworkInterface object pointer for the network adapter [note: we assume connect has already been called on this]). - if not available use NULL (may not be required on some OSs).
00042 * @param[out] interfaceIndex Contains the index assigned to the interface in case it has been assigned successfully. This index can be used when creating a socket to bind the socket to the interface.
00043 \return The status in the form of palStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00044 */
00045 palStatus_t pal_plat_RegisterNetworkInterface(void* networkInterfaceContext, uint32_t* interfaceIndex);
00046 
00047 /*! Initialize terminate - can be called when sockets are no longer needed to free socket resources allocated by init.
00048 * @param[in] context Optional context - if not available use NULL.
00049 \return The status in the form of palStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00050 */
00051 palStatus_t pal_plat_socketsTerminate(void* context);
00052 
00053 /*! Get a network socket.
00054 * @param[in] domain The domain of the created socket (see palSocketDomain_t for supported types).
00055 * @param[in] type The type of the created socket (see palSocketType_t for supported types).
00056 * @param[in] nonBlockingSocket If true, the socket is non-blocking (with O_NONBLOCK set).
00057 * @param[in] interfaceNum The number of the network interface used for this socket (info in interfaces supported via pal_getNumberOfNetInterfaces and pal_getNetInterfaceInfo ), choose PAL_NET_DEFAULT_INTERFACE for default interface.
00058 * @param[out] socket The socket is returned through this output parameter.
00059 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00060 */
00061 palStatus_t pal_plat_socket(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palSocket_t* socket);
00062 
00063 /*! Get options for a given network socket. Only a few options are supported (see palSocketOptionName_t for supported options).
00064 * @param[in] socket The socket for which to get options.
00065 * @param[in] optionName The name for which to set the option (see enum PAL_NET_SOCKET_OPTION for supported types).
00066 * @param[out] optionValue The buffer holding the option value returned by the function.
00067 * @param[in, out] optionLength The size of the buffer provided for optionValue when calling the function. After the call, it contains the length of data actually written to the optionValue buffer.
00068 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00069 */
00070 palStatus_t pal_plat_getSocketOptions(palSocket_t socket, palSocketOptionName_t optionName, void* optionValue, palSocketLength_t* optionLength);
00071 
00072 /*! Set options for a given network socket. Only a few options are supported (see palSocketOptionName_t for supported options).
00073 * @param[in] socket The socket for which to get options.
00074 * @param[in] optionName The name for which to set the option (see enum PAL_NET_SOCKET_OPTION for supported types).
00075 * @param[in] optionValue The buffer holding the option value to set for the given option.
00076 * @param[in] optionLength The size of the buffer provided for optionValue.
00077 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00078 */
00079 palStatus_t pal_plat_setSocketOptions(palSocket_t socket, int optionName, const void* optionValue, palSocketLength_t optionLength);
00080 
00081 /*! Bind a given socket to a local address.
00082 * @param[in] socket The socket to bind.
00083 * @param[in] myAddress The address to bind to.
00084 * @param[in] addressLength The length of the address passed in myAddress.
00085 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00086 */
00087 palStatus_t pal_plat_bind(palSocket_t socket, palSocketAddress_t* myAddress, palSocketLength_t addressLength);
00088 
00089 /*! Receive a payload from the given socket.
00090 * @param[in] socket The socket to receive from [sockets passed to this function should be of type PAL_SOCK_DGRAM (the implementation may support other types as well)].
00091 * @param[out] buffer The buffer for the payload data.
00092 * @param[in] length The length of the buffer for the payload data.
00093 * @param[out] from The address that sent the payload [optional - if not required pass NULL].
00094 * @param[in, out] fromLength The length of the 'from' address. When completed, this contains the amount of data actually written to the from address [optional - if not required pass NULL].
00095 * @param[out] bytesReceived The actual amount of payload data received to the buffer.
00096 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00097 */
00098 palStatus_t pal_plat_receiveFrom(palSocket_t socket, void* buffer, size_t length, palSocketAddress_t* from, palSocketLength_t* fromLength, size_t* bytesReceived);
00099 
00100 /*! Send a payload to the given address using the given socket.
00101 * @param[in] socket The socket to use for sending the payload [sockets passed to this function should be of type PAL_SOCK_DGRAM (the implementation may support other types as well)].
00102 * @param[in] buffer The buffer for the payload data.
00103 * @param[in] length The length of the buffer for the payload data.
00104 * @param[in] to The address to which the payload should be sent.
00105 * @param[in] toLength The length of the 'to' address.
00106 * @param[out] bytesSent The actual amount of payload data sent.
00107 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00108 */
00109 palStatus_t pal_plat_sendTo(palSocket_t socket, const void* buffer, size_t length, const palSocketAddress_t* to, palSocketLength_t toLength, size_t* bytesSent);
00110 
00111 /*! Close a network socket. 
00112 * NOTE: recieves palSocket_t* and not palSocket_t so that it can zero the socket to avoid re-use.
00113 * @param[in,out] socket Release and zero socket pointed to by given pointer.
00114 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00115 */
00116 palStatus_t pal_plat_close(palSocket_t* socket);
00117 
00118 /*! Get the number of current network interfaces (interfaces that have been registered through).
00119 * @param[out] numInterfaces The number of interfaces after a successful call.
00120 \return The status as in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00121 */
00122 palStatus_t pal_plat_getNumberOfNetInterfaces(uint32_t* numInterfaces);
00123 
00124 /*! Get information regarding the socket at the index/interface number given (this number is returned when registering the socket).
00125 * @param[in] interfaceNum The number of the interface to get information for.
00126 * @param[out] interfaceInfo The information for the given interface number.
00127 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00128 */
00129 palStatus_t pal_plat_getNetInterfaceInfo(uint32_t interfaceNum, palNetInterfaceInfo_t * interfaceInfo);
00130 
00131 
00132 /*! Check if one or more (up to PAL_NET_SOCKET_SELECT_MAX_SOCKETS) sockets has data available for reading/writing/error. The function blocks until data is available for one of the given sockets or the timeout expires.
00133 To use the function, set the sockets you want to check in the socketsToCheck array and set a timeout. When it returns the socketStatus output inidcates the status of each socket passed in.
00134 Note: The entry in index x in the socketStatus array corresponds to the socket at index x in the sockets to check array.
00135 * @param[in] socketsToCheck The array of up to 8 socket handles to check.
00136 * @param[in] numberOfSockets The number of sockets set in the input socketsToCheck array.
00137 * @param[in] timeout The time until timeout if no socket activity is detected.
00138 * @param[out] palSocketStatus Information on each socket in the input array indicating which event was set (none, rx, tx, err). Check for a desired event using macros.
00139 * @param[out] numberOfSocketsSet The total number of sockets set in all three data sets (tx, rx, err) after a completed function.
00140 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00141 */
00142 palStatus_t pal_plat_socketMiniSelect(const palSocket_t socketsToCheck[PAL_NET_SOCKET_SELECT_MAX_SOCKETS], uint32_t numberOfSockets, pal_timeVal_t* timeout,
00143                                         uint8_t palSocketStatus[PAL_NET_SOCKET_SELECT_MAX_SOCKETS], uint32_t * numberOfSocketsSet);
00144 
00145 
00146 #if PAL_NET_TCP_AND_TLS_SUPPORT // functionality below supported only in case TCP is supported.
00147 
00148 
00149 /*! Use a socket to listen to incoming connections. You may also limit the queue of incoming connections.
00150 * @param[in] socket The socket to listen to [sockets passed to this function should be of type PAL_SOCK_STREAM_SERVER (the implementation may support other types as well)].
00151 * @param[in] backlog The number of pending connections that can be saved for the socket.
00152 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00153 */
00154 palStatus_t pal_plat_listen(palSocket_t socket, int backlog);
00155 
00156 /*! Accept a connection on the given socket.
00157 * @param[in] socket The socket on which to accept the connection. The socket needs to be created and bound and listen must have been called on it. [sockets passed to this function should be of type PAL_SOCK_STREAM_SERVER (the implementation may support other types as well)].
00158 * @param[out] address The source address of the incoming connection.
00159 * @param[in, out] addressLen The length of the address field on input, the length of the data returned on output.
00160 * @param[out] acceptedSocket The socket of the accepted connection is returned if the connection is accepted successfully.
00161 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00162 */
00163 palStatus_t pal_plat_accept(palSocket_t socket, palSocketAddress_t* address, palSocketLength_t* addressLen, palSocket_t* acceptedSocket);
00164 
00165 /*! Open a connection from the given socket to the given address.
00166 * @param[in] socket The socket to use for the connection to the given address [sockets passed to this function should be of type PAL_SOCK_STREAM (the implementation may support other types as well)].
00167 * @param[in] address The destination address of the connection.
00168 * @param[in] addressLen The length of the address field.
00169 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00170 */
00171 palStatus_t pal_plat_connect(palSocket_t socket, const palSocketAddress_t* address, palSocketLength_t addressLen);
00172 
00173 /*! Receive data from the given connected socket.
00174 * @param[in] socket The connected socket on which to receive data [sockets passed to this function should be of type PAL_SOCK_STREAM (the implementation may support other types as well)].
00175 * @param[out] buf The output buffer for the message data.
00176 * @param[in] len The length of the input data buffer.
00177 * @param[out] recievedDataSize The length of the data actually received.
00178 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00179 */
00180 palStatus_t pal_plat_recv(palSocket_t socket, void* buf, size_t len, size_t* recievedDataSize);
00181 
00182 /*! Send a given buffer via the given connected socket.
00183 * @param[in] socket The connected socket on which to send data [sockets passed to this function should be of type PAL_SOCK_STREAM (the implementation may support other types as well)].
00184 * @param[in] buf The output buffer for the message data.
00185 * @param[in] len The length of the input data buffer.
00186 * @param[out] sentDataSize The length of the data sent.
00187 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00188 */
00189 palStatus_t pal_plat_send(palSocket_t socket, const void* buf, size_t len, size_t* sentDataSize);
00190 
00191 
00192 #endif //PAL_NET_TCP_AND_TLS_SUPPORT
00193 
00194 
00195 #if PAL_NET_ASYNCHRONOUS_SOCKET_API
00196 
00197 /*! Get an asynchronous network socket.
00198 * @param[in] domain The domain of the created socket (see enum palSocketDomain_t for supported types).
00199 * @param[in] type The type of the created socket (see enum palSocketType_t for supported types).
00200 * @param[in] callback A callback function that is called when any supported event takes place in the given asynchronous socket (see palAsyncSocketCallbackType enum for the supported event types).
00201 * @param[out] socket This output parameter returns the socket.
00202 \return The status in the form of PalStatus_t; PAL_SUCCESS (0) in case of success, a specific negative error code in case of failure.
00203 */
00204 palStatus_t pal_plat_asynchronousSocket(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, palSocket_t* socket);
00205 
00206 #endif
00207 
00208 #if PAL_NET_DNS_SUPPORT
00209 
00210 /*! This function translates the URL to a palSocketAddress_t that can be used with PAL sockets.
00211 * @param[in] url The URL to be translated to a palSocketAddress_t.
00212 * @param[out] address The address for the output of the translation.
00213 */
00214 palStatus_t pal_plat_getAddressInfo(const char* url, palSocketAddress_t* address, palSocketLength_t* addressLength);
00215 
00216 #endif
00217 
00218 
00219 #ifdef __cplusplus
00220 }
00221 #endif
00222 #endif //_PAL_PLAT_SOCKET_H