nl::Inet::InetLayer

#include <src/inet/InetLayer.h>

This provides access to Internet services, including timers, Domain Name System (DNS) resolution, TCP network transport, UDP network transport, and raw network transport, for a single thread.

Summary

For BSD/POSIX Sockets, event readiness notification is handled via file descriptors and a traditional poll / select implementation on the platform adaptation.

For LwIP, event readiness notification is handle via events / messages and platform- and system-specific hooks for the event / message system.

Constructors and Destructors
InetLayer(void)
This is the InetLayer default constructor.

Public types
@5{
  kState_NotInitialized = 0,
  kState_Initialized = 1,
  kState_ShutdownInProgress = 2
} 		enum
The current state of the InetLayer object.
DNSResolveCompleteFunct typedef
DNSResolver::OnResolveCompleteFunct

Public attributes
State
enum nl::Inet::InetLayer::@5
The current state of the InetLayer object.

Public static attributes
sInetEventHandlerDelegate

Public functions
CanEnqueueDroppableEvent(void)
bool
CancelResolveHostAddress(DNSResolveCompleteFunct onComplete, void *appState)
void
Cancel any outstanding DNS query (for a matching completion callback and application state) that may still be active.
DroppableEventDequeued(void)
void
GetInterfaceFromAddr(const IPAddress & addr, InterfaceId & intfId)
Get the interface identifier for the specified IP address.
GetLinkLocalAddr(InterfaceId link, IPAddress *llAddr)
Get the link local IPv6 address for a specified link or interface.
GetPlatformData(void)
void *
This returns any client-specific platform data assigned to the instance, if it has been previously set.
HandleSelectResult(int selectRes, fd_set *readfds, fd_set *writefds, fd_set *exceptfds)
void
Handle I/O from a select call.
Init(Weave::System::Layer & aSystemLayer, void *aContext)
This is the InetLayer explicit initializer.
InitQueueLimiter(void)
MatchLocalIPv6Subnet(const IPAddress & addr)
bool
Check if there is a prefix match between the specified IPv6 address and any of the locally configured IPv6 addresses.
NewRawEndPoint(IPVersion ipVer, IPProtocol ipProto, RawEndPoint **retEndPoint)
Creates a new RawEndPoint object for a specific IP version and protocol.
NewTCPEndPoint(TCPEndPoint **retEndPoint)
Creates a new TCPEndPoint object.
NewTunEndPoint(TunEndPoint **retEndPoint)
Creates a new TunEndPoint object.
NewUDPEndPoint(UDPEndPoint **retEndPoint)
Creates a new UDPEndPoint object.
PrepareSelect(int & nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval & sleepTime)
void
Prepare the sets of file descriptors for select() to work with.
ResolveHostAddress(const char *hostName, uint16_t hostNameLen, uint8_t options, uint8_t maxAddrs, IPAddress *addrArray, DNSResolveCompleteFunct onComplete, void *appState)
Perform an IP address resolution of a specified hostname.
ResolveHostAddress(const char *hostName, uint16_t hostNameLen, uint8_t maxAddrs, IPAddress *addrArray, DNSResolveCompleteFunct onComplete, void *appState)
Perform an IP address resolution of a specified hostname.
ResolveHostAddress(const char *hostName, uint8_t maxAddrs, IPAddress *addrArray, DNSResolveCompleteFunct onComplete, void *appState)
Perform an IP address resolution of a specified hostname.
SetPlatformData(void *aPlatformData)
void
This sets the specified client-specific platform data to the instance for later retrieval by the client platform.
Shutdown(void)
This is the InetLayer explicit deinitializer and should be called prior to disposing of an instantiated InetLayer instance.
SystemLayer(void) const

Public static functions
HandleInetLayerEvent(Weave::System::Object & aTarget, Weave::System::EventType aEventType, uintptr_t aArgument)
Weave::System::Error
IsDroppableEvent(Weave::System::EventType aType)
bool
UpdateSnapshot(nl::Weave::System::Stats::Snapshot & aSnapshot)
void

Public types

@5

 @5

The current state of the InetLayer object.

Properties
kState_Initialized

Initialized state.

kState_NotInitialized

Not initialized state.

kState_ShutdownInProgress

State where Shutdown has been triggered.

DNSResolveCompleteFunct

DNSResolver::OnResolveCompleteFunct DNSResolveCompleteFunct

Public attributes

State

enum nl::Inet::InetLayer::@5 State

The current state of the InetLayer object.

[READ-ONLY] Current state.

Public static attributes

sInetEventHandlerDelegate

Weave::System::LwIPEventHandlerDelegate sInetEventHandlerDelegate

Public functions

CanEnqueueDroppableEvent

bool CanEnqueueDroppableEvent(
  void
)

CancelResolveHostAddress

void CancelResolveHostAddress(
  DNSResolveCompleteFunct onComplete,
  void *appState
)

Cancel any outstanding DNS query (for a matching completion callback and application state) that may still be active.

Details
Parameters
[in] onComplete
A pointer to the callback function when a DNS request is complete.
[in] appState
A pointer to an application state object to be passed to the callback function as argument.

DroppableEventDequeued

void DroppableEventDequeued(
  void
)

GetInterfaceFromAddr

INET_ERROR GetInterfaceFromAddr(
  const IPAddress & addr,
  InterfaceId & intfId
)

Get the interface identifier for the specified IP address.

If the interface identifier cannot be derived it is set to the INET_NULL_INTERFACEID.

Details
Parameters
[in] addr
A reference to the IPAddress object.
[out] intfId
A reference to the InterfaceId object.
Returns
INET_NO_ERROR unconditionally.

GetLinkLocalAddr

INET_ERROR GetLinkLocalAddr(
  InterfaceId link,
  IPAddress *llAddr
)

Get the link local IPv6 address for a specified link or interface.

Details
Parameters
[in] link
The interface for which the link local IPv6 address is being sought.
[out] llAddr
The link local IPv6 address for the link.
Return Values
INET_ERROR_NOT_IMPLEMENTED
If IPv6 is not supported.
INET_ERROR_BAD_ARGS
If the link local address is NULL.
INET_ERROR_ADDRESS_NOT_FOUND
If the link does not have any address configured.
INET_NO_ERROR
On success.

GetPlatformData

void * GetPlatformData(
  void
)

This returns any client-specific platform data assigned to the instance, if it has been previously set.

Details
Returns
Client-specific platform data, if is has been previously set; otherwise, NULL.

HandleSelectResult

void HandleSelectResult(
  int selectRes,
  fd_set *readfds,
  fd_set *writefds,
  fd_set *exceptfds
)

Handle I/O from a select call.

This method registers the pending I/O event in each active endpoint and then invokes the respective I/O handling functions for those endpoints.

Details
Parameters
[in] selectRes
The return value of the select call.
[in] readfds
A pointer to the set of read file descriptors.
[in] writefds
A pointer to the set of write file descriptors.
[in] exceptfds
A pointer to the set of file descriptors with errors.

InetLayer

 InetLayer(
  void
)

This is the InetLayer default constructor.

It performs some basic data member initialization; however, since InetLayer follows an explicit initializer design pattern, the InetLayer::Init method must be called successfully prior to using the object.

Init

INET_ERROR Init(
  Weave::System::Layer & aSystemLayer,
  void *aContext
)

This is the InetLayer explicit initializer.

This must be called and complete successfully before the InetLayer may be used.

The caller may provide an optional context argument which will be passed back via any platform-specific hook functions. For LwIP-based adaptations, this will typically be a pointer to the event queue associated with the InetLayer instance.

Platforms may choose to assert INET_CONFIG_WILL_OVERRIDE_PLATFORM_XTOR_FUNCS in their platform-specific configuration header and enable the Platform::InetLayer::WillInit and Platform::InetLayer::DidInit hooks to effect platform-specific customizations or data extensions to InetLayer.

Details
Parameters
[in] aSystemLayer
A required instance of the Weave System Layer already successfully initialized.
[in] aContext
An optional context argument which will be passed back to the caller via any platform-specific hook functions.
Return Values
INET_ERROR_INCORRECT_STATE
If the InetLayer is in an incorrect state.
INET_ERROR_NO_MEMORY
If the InetLayer runs out of resource for this request for a new timer.
other
Platform-specific errors indicating the reason for initialization failure.
INET_NO_ERROR
On success.

InitQueueLimiter

INET_ERROR InitQueueLimiter(
  void
)

MatchLocalIPv6Subnet

bool MatchLocalIPv6Subnet(
  const IPAddress & addr
)

Check if there is a prefix match between the specified IPv6 address and any of the locally configured IPv6 addresses.

Details
Parameters
[in] addr
The IPv6 address to check for the prefix-match.
Returns
true if a successful match is found, otherwise false.

NewRawEndPoint

INET_ERROR NewRawEndPoint(
  IPVersion ipVer,
  IPProtocol ipProto,
  RawEndPoint **retEndPoint
)

Creates a new RawEndPoint object for a specific IP version and protocol.

Details
Parameters
[in] ipVer
IPv4 or IPv6.
[in] ipProto
A protocol within the IP family (e.g., ICMPv4 or ICMPv6).
[in,out] retEndPoint
A pointer to a pointer of the RawEndPoint object that is a return parameter upon completion of the object creation. *retEndPoint is NULL if creation fails.
Return Values
INET_ERROR_INCORRECT_STATE
If the InetLayer object is not initialized.
INET_ERROR_NO_ENDPOINTS
If the InetLayerRawEndPoint pool is full and no new endpoints can be created.
INET_NO_ERROR
On success.

NewTCPEndPoint

INET_ERROR NewTCPEndPoint(
  TCPEndPoint **retEndPoint
)

Creates a new TCPEndPoint object.

Details
Parameters
[in,out] retEndPoint
A pointer to a pointer of the TCPEndPoint object that is a return parameter upon completion of the object creation. *retEndPoint is NULL if creation fails.
Return Values
INET_ERROR_INCORRECT_STATE
If the InetLayer object is not initialized.
INET_ERROR_NO_ENDPOINTS
If the InetLayerTCPEndPoint pool is full and no new endpoints can be created.
INET_NO_ERROR
On success.

NewTunEndPoint

INET_ERROR NewTunEndPoint(
  TunEndPoint **retEndPoint
)

Creates a new TunEndPoint object.

Details
Parameters
[in,out] retEndPoint
A pointer to a pointer of the TunEndPoint object that is a return parameter upon completion of the object creation. *retEndPoint is NULL if creation fails.
Return Values
INET_ERROR_INCORRECT_STATE
If the InetLayer object is not initialized.
INET_ERROR_NO_ENDPOINTS
If the InetLayerTunEndPoint pool is full and no new ones can be created.
INET_NO_ERROR
On success.

NewUDPEndPoint

INET_ERROR NewUDPEndPoint(
  UDPEndPoint **retEndPoint
)

Creates a new UDPEndPoint object.

Details
Parameters
[in,out] retEndPoint
A pointer to a pointer of the UDPEndPoint object that is a return parameter upon completion of the object creation. *retEndPoint is NULL if creation fails.
Return Values
INET_ERROR_INCORRECT_STATE
If the InetLayer object is not initialized.
INET_ERROR_NO_ENDPOINTS
If the InetLayerUDPEndPoint pool is full and no new endpoints can be created.
INET_NO_ERROR
On success.

PrepareSelect

void PrepareSelect(
  int & nfds,
  fd_set *readfds,
  fd_set *writefds,
  fd_set *exceptfds,
  struct timeval & sleepTime
)

Prepare the sets of file descriptors for select() to work with.

Details
Parameters
[out] nfds
The range of file descriptors in the file descriptor set.
[in] readfds
A pointer to the set of readable file descriptors.
[in] writefds
A pointer to the set of writable file descriptors.
[in] exceptfds
A pointer to the set of file descriptors with errors.
[in] sleepTimeTV
A pointer to a structure specifying how long the select should sleep

ResolveHostAddress

INET_ERROR ResolveHostAddress(
  const char *hostName,
  uint16_t hostNameLen,
  uint8_t options,
  uint8_t maxAddrs,
  IPAddress *addrArray,
  DNSResolveCompleteFunct onComplete,
  void *appState
)

Perform an IP address resolution of a specified hostname.

Details
Parameters
[in] hostName
A pointer to a non NULL-terminated C string representing the host name to be queried.
[in] hostNameLen
The string length of host name.
[in] options
An integer value controlling how host name resolution is performed. 
                    Value should be one of the address family values from the
                    #DNSOptions enumeration:

                    #kDNSOption_AddrFamily_Any
                    #kDNSOption_AddrFamily_IPv4Only
                    #kDNSOption_AddrFamily_IPv6Only
                    #kDNSOption_AddrFamily_IPv4Preferred
                    #kDNSOption_AddrFamily_IPv6Preferred
[in] maxAddrs
The maximum number of addresses to store in the DNS table.
[in] addrArray
A pointer to the DNS table.
[in] onComplete
A pointer to the callback function when a DNS request is complete.
[in] appState
A pointer to the application state to be passed to onComplete when a DNS request is complete.
Return Values
INET_NO_ERROR
if a DNS request is handled successfully.
INET_ERROR_NO_MEMORY
if the Inet layer resolver pool is full.
INET_ERROR_HOST_NAME_TOO_LONG
if a requested host name is too long.
INET_ERROR_HOST_NOT_FOUND
if a request host name could not be resolved to an address.
INET_ERROR_DNS_TRY_AGAIN
if a name server returned a temporary failure indication; try again later.
INET_ERROR_DNS_NO_RECOVERY
if a name server returned an unrecoverable error.
INET_ERROR_NOT_IMPLEMENTED
if DNS resolution is not enabled on the underlying platform.
other
POSIX network or OS error returned by the underlying DNS resolver implementation.

ResolveHostAddress

INET_ERROR ResolveHostAddress(
  const char *hostName,
  uint16_t hostNameLen,
  uint8_t maxAddrs,
  IPAddress *addrArray,
  DNSResolveCompleteFunct onComplete,
  void *appState
)

Perform an IP address resolution of a specified hostname.

Details
Parameters
[in] hostName
A pointer to a non NULL-terminated C string representing the host name to be queried.
[in] hostNameLen
The string length of host name.
[in] maxAddrs
The maximum number of addresses to store in the DNS table.
[in] addrArray
A pointer to the DNS table.
[in] onComplete
A pointer to the callback function when a DNS request is complete.
[in] appState
A pointer to the application state to be passed to onComplete when a DNS request is complete.
Return Values
INET_NO_ERROR
if a DNS request is handled successfully.
INET_ERROR_NO_MEMORY
if the Inet layer resolver pool is full.
INET_ERROR_HOST_NAME_TOO_LONG
if a requested host name is too long.
INET_ERROR_HOST_NOT_FOUND
if a request host name could not be resolved to an address.
INET_ERROR_DNS_TRY_AGAIN
if a name server returned a temporary failure indication; try again later.
INET_ERROR_DNS_NO_RECOVERY
if a name server returned an unrecoverable error.
INET_ERROR_NOT_IMPLEMENTED
if DNS resolution is not enabled on the underlying platform.
other
POSIX network or OS error returned by the underlying DNS resolver implementation.

ResolveHostAddress

INET_ERROR ResolveHostAddress(
  const char *hostName,
  uint8_t maxAddrs,
  IPAddress *addrArray,
  DNSResolveCompleteFunct onComplete,
  void *appState
)

Perform an IP address resolution of a specified hostname.

Details
Parameters
[in] hostName
A pointer to a NULL-terminated C string representing the host name to be queried.
[in] maxAddrs
The maximum number of addresses to store in the DNS table.
[in] addrArray
A pointer to the DNS table.
[in] onComplete
A pointer to the callback function when a DNS request is complete.
[in] appState
A pointer to the application state to be passed to onComplete when a DNS request is complete.
Return Values
INET_NO_ERROR
if a DNS request is handled successfully.
INET_ERROR_NO_MEMORY
if the Inet layer resolver pool is full.
INET_ERROR_HOST_NAME_TOO_LONG
if a requested host name is too long.
INET_ERROR_HOST_NOT_FOUND
if a request host name could not be resolved to an address.
INET_ERROR_DNS_TRY_AGAIN
if a name server returned a temporary failure indication; try again later.
INET_ERROR_DNS_NO_RECOVERY
if a name server returned an unrecoverable error.
INET_ERROR_NOT_IMPLEMENTED
if DNS resolution is not enabled on the underlying platform.
other
POSIX network or OS error returned by the underlying DNS resolver implementation.

SetPlatformData

void SetPlatformData(
  void *aPlatformData
)

This sets the specified client-specific platform data to the instance for later retrieval by the client platform.

Details
Parameters
[in] aPlatformData
The client-specific platform data to set.

Shutdown

INET_ERROR Shutdown(
  void
)

This is the InetLayer explicit deinitializer and should be called prior to disposing of an instantiated InetLayer instance.

Platforms may choose to assert INET_CONFIG_WILL_OVERRIDE_PLATFORM_XTOR_FUNCS in their platform-specific configuration header and enable the Platform::InetLayer::WillShutdown and Platform::InetLayer::DidShutdown hooks to effect clean-up of platform-specific customizations or data extensions to InetLayer.

Details
Returns
INET_NO_ERROR on success; otherwise, a specific error indicating the reason for shutdown failure.

SystemLayer

Weave::System::Layer * SystemLayer(
  void
) const

Public static functions

HandleInetLayerEvent

Weave::System::Error HandleInetLayerEvent(
  Weave::System::Object & aTarget,
  Weave::System::EventType aEventType,
  uintptr_t aArgument
)

IsDroppableEvent

bool IsDroppableEvent(
  Weave::System::EventType aType
)

UpdateSnapshot

void UpdateSnapshot(
  nl::Weave::System::Stats::Snapshot & aSnapshot
)