Mistake on this page? Email us
pal_network.h
Go to the documentation of this file.
1 // ----------------------------------------------------------------------------
2 // Copyright 2016-2021 Pelion.
3 //
4 // SPDX-License-Identifier: Apache-2.0
5 //
6 // Licensed under the Apache License, Version 2.0 (the "License");
7 // you may not use this file except in compliance with the License.
8 // You may obtain a copy of the License at
9 //
10 // http://www.apache.org/licenses/LICENSE-2.0
11 //
12 // Unless required by applicable law or agreed to in writing, software
13 // distributed under the License is distributed on an "AS IS" BASIS,
14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 // See the License for the specific language governing permissions and
16 // limitations under the License.
17 // ----------------------------------------------------------------------------
18 
19 #ifndef _PAL_SOCKET_H
20 #define _PAL_SOCKET_H
21 
22 #ifndef _PAL_H
23 #error "Please do not include this file directly, use pal.h instead"
24 #endif
25 
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
43 typedef uint32_t palSocketLength_t;
44 typedef void *palSocket_t;
46 #define PAL_NET_MAX_ADDR_SIZE 32 // check if we can make this more efficient
47 
48 typedef struct palSocketAddress {
49  unsigned short addressType;
53 #if PAL_NET_DNS_SUPPORT
54 #if (PAL_DNS_API_VERSION == 3)
55 typedef void *palAddressInfo_t;
56 #endif // (PAL_DNS_API_VERSION == 3)
57 #endif // PAL_NET_DNS_SUPPORT
58 
59 typedef struct palNetInterfaceInfo {
60  char interfaceName[16]; //15 + ‘\0’
62  uint32_t addressSize;
64 
66 typedef enum {
69  PAL_AF_INET6 = 10,
71 
73 typedef enum {
77 
79 typedef enum {
80 #if PAL_NET_TCP_AND_TLS_SUPPORT
81  PAL_SOCK_STREAM = 1,
82  PAL_SOCK_STREAM_SERVER = 99,
83 #endif //PAL_NET_TCP_AND_TLS_SUPPORT
86 
88 typedef enum {
89  PAL_SO_REUSEADDR = 0x0004,
90 #if PAL_NET_TCP_AND_TLS_SUPPORT // Socket options below supported only if TCP is supported.
91  PAL_SO_KEEPALIVE = 0x0008,
92  PAL_SO_KEEPIDLE = 0x0009,
93  PAL_SO_KEEPINTVL = 0x0010,
94 #endif //PAL_NET_TCP_AND_TLS_SUPPORT
95  PAL_SO_SNDTIMEO = 0x1005,
96  PAL_SO_RCVTIMEO = 0x1006,
100 
102 typedef enum {
106 
107 #define PAL_NET_DEFAULT_INTERFACE 0xFFFFFFFF
108 
109 #define PAL_IPV4_ADDRESS_SIZE 4
110 #define PAL_IPV6_ADDRESS_SIZE 16
111 
114 
115 typedef void(*connectionStatusCallback)(palNetworkStatus_t status, void *client_arg);
116 
129 palStatus_t pal_registerNetworkInterface(void *networkInterfaceContext, uint32_t *interfaceIndex);
130 
135 palStatus_t pal_unregisterNetworkInterface(uint32_t interfaceIndex);
136 
144 palStatus_t pal_setSockAddrPort(palSocketAddress_t *address, uint16_t port);
145 
151 palStatus_t pal_setSockAddrIPV4Addr(palSocketAddress_t *address, palIpV4Addr_t ipV4Addr);
152 
158 palStatus_t pal_getSockAddrIPV4Addr(const palSocketAddress_t *address, palIpV4Addr_t ipV4Addr);
159 
165 palStatus_t pal_setSockAddrIPV6Addr(palSocketAddress_t *address, palIpV6Addr_t ipV6Addr);
166 
172 palStatus_t pal_getSockAddrIPV6Addr(const palSocketAddress_t *address, palIpV6Addr_t ipV6Addr);
173 
179 palStatus_t pal_setSockAddrNAT64Addr(palSocketAddress_t *address, palIpV4Addr_t ipV4Addr);
180 
186 palStatus_t pal_getSockAddrPort(const palSocketAddress_t *address, uint16_t *port);
187 
195 palStatus_t pal_setSocketOptions(palSocket_t socket, int optionName, const void *optionValue, palSocketLength_t optionLength);
196 
205 palStatus_t pal_setSocketOptionsWithLevel(palSocket_t socket, palSocketOptionLevelName_t optionLevel, int optionName, const void *optionValue, palSocketLength_t optionLength);
206 
212 palStatus_t pal_isNonBlocking(palSocket_t socket, bool *isNonBlocking);
213 
220 palStatus_t pal_bind(palSocket_t socket, palSocketAddress_t *myAddress, palSocketLength_t addressLength);
221 
231 palStatus_t pal_receiveFrom(palSocket_t socket, void *buffer, size_t length, palSocketAddress_t *from, palSocketLength_t *fromLength, size_t *bytesReceived);
232 
242 palStatus_t pal_sendTo(palSocket_t socket, const void *buffer, size_t length, const palSocketAddress_t *to, palSocketLength_t toLength, size_t *bytesSent);
243 
249 palStatus_t pal_close(palSocket_t *socket);
250 
255 palStatus_t pal_getNumberOfNetInterfaces(uint32_t *numInterfaces);
256 
262 palStatus_t pal_getNetInterfaceInfo(uint32_t interfaceNum, palNetInterfaceInfo_t *interfaceInfo);
263 
270 palStatus_t pal_setConnectionStatusCallback(uint32_t interfaceNum, connectionStatusCallback callback, void *client_arg);
271 
272 #define PAL_NET_SOCKET_SELECT_MAX_SOCKETS 8
273 #define PAL_NET_SOCKET_SELECT_RX_BIT (1)
274 #define PAL_NET_SOCKET_SELECT_TX_BIT (2)
275 #define PAL_NET_SOCKET_SELECT_ERR_BIT (4)
276 
277 #define PAL_NET_SELECT_IS_RX(socketStatus, index) ((socketStatus[index] & PAL_NET_SOCKET_SELECT_RX_BIT) != 0)
278 #define PAL_NET_SELECT_IS_TX(socketStatus, index) ((socketStatus[index] & PAL_NET_SOCKET_SELECT_TX_BIT) != 0)
279 #define PAL_NET_SELECT_IS_ERR(socketStatus, index) ((socketStatus[index] & PAL_NET_SOCKET_SELECT_ERR_BIT) != 0)
284 typedef void(*palAsyncSocketCallback_t)(void *);
285 
286 #if PAL_NET_TCP_AND_TLS_SUPPORT // The functionality below is supported only if TCP is supported.
287 
288 #if PAL_NET_SERVER_SOCKET_API
289 
295 palStatus_t pal_listen(palSocket_t socket, int backlog);
296 
306 palStatus_t pal_accept(palSocket_t socket, palSocketAddress_t *address, palSocketLength_t *addressLen, palSocket_t *acceptedSocket, palAsyncSocketCallback_t callback, void *callbackArgument);
307 
308 #endif // PAL_NET_SERVER_SOCKET_API
309 
316 palStatus_t pal_connect(palSocket_t socket, const palSocketAddress_t *address, palSocketLength_t addressLen);
317 
325 palStatus_t pal_recv(palSocket_t socket, void *buf, size_t len, size_t *recievedDataSize);
326 
334 palStatus_t pal_send(palSocket_t socket, const void *buf, size_t len, size_t *sentDataSize);
335 
336 
337 #endif //PAL_NET_TCP_AND_TLS_SUPPORT
338 
348 palStatus_t pal_asynchronousSocket(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, palSocket_t *socket);
349 
360 palStatus_t pal_asynchronousSocketWithArgument(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, void *callbackArgument, palSocket_t *socket);
361 
362 
363 #if PAL_NET_DNS_SUPPORT
364 #if (PAL_DNS_API_VERSION == 0) || (PAL_DNS_API_VERSION == 1)
365 
373 palStatus_t pal_getAddressInfo(const char *hostname, palSocketAddress_t *address, palSocketLength_t *addressLength);
374 
375 #if (PAL_DNS_API_VERSION == 1)
376 
385 typedef void(*palGetAddressInfoAsyncCallback_t)(const char *hostname, palSocketAddress_t *address, palSocketLength_t *addressLength, palStatus_t status, void *callbackArgument);
386 
398 palStatus_t pal_getAddressInfoAsync(const char *hostname, palSocketAddress_t *address, palSocketLength_t *addressLength, palGetAddressInfoAsyncCallback_t callback, void *callbackArgument);
399 #endif
400 #elif (PAL_DNS_API_VERSION == 2) || (PAL_DNS_API_VERSION == 3)
401 #if (PAL_DNS_API_VERSION == 2)
402 typedef int32_t palDNSQuery_t;
411 typedef void(*palGetAddressInfoAsyncCallback_t)(const char *hostname, palSocketAddress_t *address, palStatus_t status, void *callbackArgument);
412 
421 typedef struct pal_asyncAddressInfo {
422  char *hostname;
423  palSocketAddress_t *address;
424  palGetAddressInfoAsyncCallback_t callback;
425  void *callbackArgument;
426  palDNSQuery_t *queryHandle;
427 } pal_asyncAddressInfo_t;
428 
440 palStatus_t pal_getAddressInfoAsync(const char *hostname,
441  palSocketAddress_t *address,
442  palGetAddressInfoAsyncCallback_t callback,
443  void *callbackArgument,
444  palDNSQuery_t *queryHandle);
445 
446 #elif (PAL_DNS_API_VERSION == 3)
447 typedef uintptr_t palDNSQuery_t;
455 palStatus_t pal_getDNSAddress(palAddressInfo_t *addrInfo, uint16_t index, palSocketAddress_t *addr);
456 
461 int pal_getDNSCount(palAddressInfo_t *addrInfo);
462 
466 void pal_freeAddrInfo(palAddressInfo_t *addrInfo);
467 
472 palStatus_t pal_free_addressinfoAsync(palDNSQuery_t handle);
473 
480 typedef void(*palGetAddressInfoAsyncCallback_t)(const char *hostname, palAddressInfo_t *addrInfo, palStatus_t status, void *callbackArgument);
481 
489 typedef struct pal_asyncAddressInfo
490 {
491  char* hostname;
492  palAddressInfo_t *addrInfo;
493  palGetAddressInfoAsyncCallback_t callback;
494  void* callbackArgument;
495  palDNSQuery_t *queryHandle;
496 } pal_asyncAddressInfo_t;
497 
508 palStatus_t pal_getAddressInfoAsync(const char* hostname,
509  palGetAddressInfoAsyncCallback_t callback,
510  void* callbackArgument,
511  palDNSQuery_t* queryHandle);
512 
513 #endif
514 
519 palStatus_t pal_cancelAddressInfoAsync(palDNSQuery_t queryHandle);
520 #else
521  #error "Please specify the platform PAL_DNS_API_VERSION 0, 1, 2 or 3"
522 #endif // PAL_DNS_API_VERSION
523 #endif // PAL_NET_DNS_SUPPORT
524 
535 uint8_t pal_getRttEstimate();
536 
547 uint16_t pal_getStaggerEstimate(uint16_t data_amount);
548 
558 void pal_setFixedStaggerEstimate(uint16_t stagger_estimate);
559 
560 #ifdef __cplusplus
561 }
562 #endif
563 #endif //_PAL_SOCKET_H
palStatus_t pal_getSockAddrPort(const palSocketAddress_t *address, uint16_t *port)
Get a port from an address data structure.
palStatus_t pal_sendTo(palSocket_t socket, const void *buffer, size_t length, const palSocketAddress_t *to, palSocketLength_t toLength, size_t *bytesSent)
Send a payload to an address using a specific socket.
palStatus_t pal_setSockAddrNAT64Addr(palSocketAddress_t *address, palIpV4Addr_t ipV4Addr)
Set a NAT64 address from an IPv4 address data structure and set addressType as IPv6.
Definition: pal_network.h:103
palStatus_t pal_close(palSocket_t *socket)
Close a network socket.
Use to set IPv6 traffic class priority. Default is 0.
Definition: pal_network.h:98
palStatus_t pal_getSockAddrIPV6Addr(const palSocketAddress_t *address, palIpV6Addr_t ipV6Addr)
Get an IPv6 address from an address data structure.
Definition: pal_network.h:104
Definition: pal_network.h:67
palStatus_t pal_registerNetworkInterface(void *networkInterfaceContext, uint32_t *interfaceIndex)
Register a network interface for use with PAL sockets.
struct palNetInterfaceInfo palNetInterfaceInfo_t
uint32_t palSocketLength_t
The length of data.
Definition: pal_network.h:43
palStatus_t pal_getNetInterfaceInfo(uint32_t interfaceNum, palNetInterfaceInfo_t *interfaceInfo)
Get information regarding the socket at the interface index number given. This number is returned whe...
uint8_t palIpV4Addr_t[PAL_IPV4_ADDRESS_SIZE]
Definition: pal_network.h:112
Datagram socket.
Definition: pal_network.h:84
palStatus_t pal_asynchronousSocketWithArgument(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, void *callbackArgument, palSocket_t *socket)
Get an asynchronous network socket that passes the provided callbackArgument to a specified callback ...
uint16_t pal_getStaggerEstimate(uint16_t data_amount)
This function returns the stagger estimate for registration in seconds.
palStatus_t pal_asynchronousSocket(palSocketDomain_t domain, palSocketType_t type, bool nonBlockingSocket, uint32_t interfaceNum, palAsyncSocketCallback_t callback, palSocket_t *socket)
Get an asynchronous network socket.
palSocketAddress_t address
Definition: pal_network.h:61
palStatus_t pal_isNonBlocking(palSocket_t socket, bool *isNonBlocking)
Check if a socket is non-blocking.
palStatus_t pal_setConnectionStatusCallback(uint32_t interfaceNum, connectionStatusCallback callback, void *client_arg)
Set listener for connection status events.
void * palSocket_t
PAL socket handle type.
Definition: pal_network.h:44
palStatus_t pal_setSocketOptions(palSocket_t socket, int optionName, const void *optionValue, palSocketLength_t optionLength)
Set the value for a socket option on a network socket.
palSocketOptionLevelName_t
Socket protocol level options supported by PAL.
Definition: pal_network.h:102
palStatus_t pal_setSockAddrIPV6Addr(palSocketAddress_t *address, palIpV6Addr_t ipV6Addr)
Set an IPv6 address to an address data structure and set the addressType as IPv6. ...
IP version 6.
Definition: pal_network.h:69
void pal_setFixedStaggerEstimate(uint16_t stagger_estimate)
This function sets an application defined override value for the stagger estimate for registration in...
unsigned short addressType
Address family for the socket.
Definition: pal_network.h:49
palStatus_t pal_setSocketOptionsWithLevel(palSocket_t socket, palSocketOptionLevelName_t optionLevel, int optionName, const void *optionValue, palSocketLength_t optionLength)
Set the value for a socket option on a network socket.
palSocketType_t
Socket types supported by PAL.
Definition: pal_network.h:79
Definition: pal_network.h:59
palNetworkStatus_t
Network status event.
Definition: pal_network.h:73
palStatus_t pal_setSockAddrPort(palSocketAddress_t *address, uint16_t port)
Set a port to an address data structure.
Receive timeout.
Definition: pal_network.h:96
palSocketOptionName_t
Socket options supported by PAL.
Definition: pal_network.h:88
struct palSocketAddress palSocketAddress_t
Address data structure with enough room to support IPV4 and IPV6.
Allow local address reuse.
Definition: pal_network.h:89
uint32_t addressSize
Definition: pal_network.h:62
palStatus_t pal_bind(palSocket_t socket, palSocketAddress_t *myAddress, palSocketLength_t addressLength)
Bind a socket to a local address.
uint8_t palIpV6Addr_t[PAL_IPV6_ADDRESS_SIZE]
Definition: pal_network.h:113
uint8_t pal_getRttEstimate()
This function returns the round-trip estimate for packet in seconds.
palStatus_t pal_getSockAddrIPV4Addr(const palSocketAddress_t *address, palIpV4Addr_t ipV4Addr)
Get an IPv4 address from an address data structure.
#define PAL_IPV4_ADDRESS_SIZE
Definition: pal_network.h:109
#define PAL_IPV6_ADDRESS_SIZE
Definition: pal_network.h:110
palStatus_t pal_setSockAddrIPV4Addr(palSocketAddress_t *address, palIpV4Addr_t ipV4Addr)
Set an IPv4 address to an address data structure and set addressType as IPv4.
Definition: pal_network.h:75
void(* connectionStatusCallback)(palNetworkStatus_t status, void *client_arg)
Definition: pal_network.h:115
palStatus_t pal_getNumberOfNetInterfaces(uint32_t *numInterfaces)
Get the number of current network interfaces.
void(* palAsyncSocketCallback_t)(void *)
The type of the callback function passed when creating asynchronous sockets.
Definition: pal_network.h:284
#define PAL_NET_MAX_ADDR_SIZE
Definition: pal_network.h:46
Send timeout.
Definition: pal_network.h:95
char addressData[PAL_NET_MAX_ADDR_SIZE]
Address based on the protocol used.
Definition: pal_network.h:50
int32_t palStatus_t
Definition: pal_types.h:55
Internet IP Protocol.
Definition: pal_network.h:68
palStatus_t pal_receiveFrom(palSocket_t socket, void *buffer, size_t length, palSocketAddress_t *from, palSocketLength_t *fromLength, size_t *bytesReceived)
Receive a payload from a specific socket.
palSocketDomain_t
Network domains supported by PAL.
Definition: pal_network.h:66
palStatus_t pal_unregisterNetworkInterface(uint32_t interfaceIndex)
Unregister a network interface.
Definition: pal_network.h:48
Definition: pal_network.h:74
Hop limit for subsequent multicast datagrams to be set to any value from 0 to 255. This ability is used to control the scope of the multicasts.
Definition: pal_network.h:97