nl::Inet::UDPEndPoint

#include <src/inet/UDPEndPoint.h>

Objects of this class represent UDP transport endpoints.

Summary

Nest Inet Layer encapsulates methods for interacting with UDP transport endpoints (SOCK_DGRAM sockets on Linux and BSD-derived systems) or LwIP UDP protocol control blocks, as the system is configured accordingly.

Inheritance

Inherits from: nl::Inet::EndPointBasis

Public types

@10{
  kSendFlag_RetainBuffer = 0x0040
}
enum
Transmit option flags for the SendTo methods.
@9{
  kState_Ready = kBasisState_Closed,
  kState_Bound = 1,
  kState_Listening = 2,
  kState_Closed = 3
}
enum
Basic dynamic state of the underlying endpoint.
OnMessageReceivedFunct)(UDPEndPoint *endPoint, Weave::System::PacketBuffer *msg, const IPPacketInfo *pktInfo) typedef
void(*
Type of message text reception event handling function.
OnReceiveErrorFunct)(UDPEndPoint *endPoint, INET_ERROR err, const IPPacketInfo *pktInfo) typedef
void(*
Type of reception error event handling function.

Public attributes

OnMessageReceived
The endpoint's message reception event handling function delegate.
OnReceiveError
The endpoint's receive error event handling function delegate.
mState
enum nl::Inet::UDPEndPoint::@9
Basic dynamic state of the underlying endpoint.

Public functions

Bind(IPAddressType addrType, IPAddress addr, uint16_t port, InterfaceId intfId)
Bind the endpoint to an interface IP address.
BindInterface(IPAddressType addrType, InterfaceId intf)
Bind the endpoint to a network interface.
Close(void)
void
Close the endpoint.
Free(void)
void
Close the endpoint and recycle its memory.
GetBoundInterface(void)
InterfaceId
Get the bound interface on this endpoint.
Listen(void)
Prepare the endpoint to receive UDP messages.
SendTo(IPAddress addr, uint16_t port, Weave::System::PacketBuffer *msg, uint16_t sendFlags)
A synonym for SendTo(addr, port, INET_NULL_INTERFACEID, msg, sendFlags).
SendTo(IPAddress addr, uint16_t port, InterfaceId intfId, Weave::System::PacketBuffer *msg, uint16_t sendFlags)
Send a UDP message to the specified destination address.

Public types

@10

 @10

Transmit option flags for the SendTo methods.

Properties
kSendFlag_RetainBuffer

Do not destructively queue the message directly.

Queue a copy.

@9

 @9

Basic dynamic state of the underlying endpoint.

Objects are initialized in the "ready" state, proceed to the "bound" state after binding to a local interface address, then proceed to the "listening" state when they have continuations registered for handling events for reception of UDP messages.

Note:The kBasisState_Closed state enumeration is mapped to kState_Ready for historical binary-compatibility reasons. The existing kState_Closed exists to identify separately the distinction between "not opened yet" and "previously opened now closed" that existed previously in the kState_Ready and kState_Closed states.

Properties
kState_Bound

Endpoint bound, but not listening.

kState_Closed

Endpoint closed, ready for release.

kState_Listening

Endpoint receiving datagrams.

kState_Ready

Endpoint initialized, but not open.

OnMessageReceivedFunct

void(* OnMessageReceivedFunct)(UDPEndPoint *endPoint, Weave::System::PacketBuffer *msg, const IPPacketInfo *pktInfo)

Type of message text reception event handling function.

Provide a function of this type to the OnMessageReceived delegate member to process message text reception events on endPoint where msg is the message text and pktInfo is the ancillary packet information for it.

Details
Parameters
[in] endPoint
The UDP endpoint associated with the event.
[in] msg
The message text received.
[in] pktInfo
The ancillary packet information.

OnReceiveErrorFunct

void(* OnReceiveErrorFunct)(UDPEndPoint *endPoint, INET_ERROR err, const IPPacketInfo *pktInfo)

Type of reception error event handling function.

Provide a function of this type to the OnReceiveError delegate member to process reception acceptance error events on endPoint. The err argument provides specific detail about the type of the error, and pktInfo is the ancillary packet information associated with the reception event.

Details
Parameters
[in] endPoint
The raw endpoint associated with the event.
[in] err
The reason for the error.
[in] pktInfo
The ancillary packet information.

Public attributes

OnMessageReceived

OnMessageReceivedFunct OnMessageReceived

The endpoint's message reception event handling function delegate.

OnReceiveError

OnReceiveErrorFunct OnReceiveError

The endpoint's receive error event handling function delegate.

mState

enum nl::Inet::UDPEndPoint::@9 mState

Basic dynamic state of the underlying endpoint.

Objects are initialized in the "ready" state, proceed to the "bound" state after binding to a local interface address, then proceed to the "listening" state when they have continuations registered for handling events for reception of UDP messages.

Note:The kBasisState_Closed state enumeration is mapped to kState_Ready for historical binary-compatibility reasons. The existing kState_Closed exists to identify separately the distinction between "not opened yet" and "previously opened now closed" that existed previously in the kState_Ready and kState_Closed states.

Public functions

Bind

INET_ERROR Bind(
  IPAddressType addrType,
  IPAddress addr,
  uint16_t port,
  InterfaceId intfId
)

Bind the endpoint to an interface IP address.

already acquired.

Details
Parameters
[in] addrType
the protocol version of the IP address
[in] addr
the IP address (must be an interface address)
[in] port
the UDP port
[in] intfId
an optional network interface indicator
Return Values
INET_NO_ERROR
success: endpoint bound to address
INET_ERROR_INCORRECT_STATE
endpoint has been bound previously
INET_NO_MEMORY
insufficient memory for endpoint
INET_ERROR_UNKNOWN_INTERFACE
On some platforms, the optionally specified interface is not present.
INET_ERROR_WRONG_PROTOCOL_TYPE
addrType does not match IPVer.
INET_ERROR_WRONG_ADDRESS_TYPE
addrType is kIPAddressType_Any, or the type of addr is not equal to addrType.
other
another system or platform error

BindInterface

INET_ERROR BindInterface(
  IPAddressType addrType,
  InterfaceId intf
)

Bind the endpoint to a network interface.

Binds the endpoint to the specified network interface IP address.

Details
Parameters
[in] addrType
the protocol version of the IP address
[in] intf
indicator of the network interface.
Return Values
INET_NO_ERROR
success: endpoint bound to address
INET_NO_MEMORY
insufficient memory for endpoint
INET_ERROR_NOT_IMPLEMENTED
system implementation not complete.
INET_ERROR_UNKNOWN_INTERFACE
On some platforms, the interface is not present.
other
another system or platform error

On LwIP, this method must not be called with the LwIP stack lock already acquired.

Close

void Close(
  void
)

Close the endpoint.

If mState != kState_Closed, then closes the endpoint, removing it from the set of endpoints eligible for communication events.

On LwIP systems, this method must not be called with the LwIP stack lock already acquired.

Free

void Free(
  void
)

Close the endpoint and recycle its memory.

Invokes the Close method, then invokes the InetLayerBasis::Release method to return the object to its memory pool.

On LwIP systems, this method must not be called with the LwIP stack lock already acquired.

GetBoundInterface

InterfaceId GetBoundInterface(
  void
)

Get the bound interface on this endpoint.

Details
Returns
InterfaceId The bound interface id.

Listen

INET_ERROR Listen(
  void
)

Prepare the endpoint to receive UDP messages.

If State is already kState_Listening, then no operation is performed, otherwise the State is set to kState_Listening and the endpoint is prepared to received UDP messages, according to the semantics of the platform.

Details
Return Values
INET_NO_ERROR
success: endpoint ready to receive messages.
INET_ERROR_INCORRECT_STATE
endpoint is already listening.

On LwIP, this method must not be called with the LwIP stack lock already acquired

SendTo

INET_ERROR SendTo(
  IPAddress addr,
  uint16_t port,
  Weave::System::PacketBuffer *msg,
  uint16_t sendFlags
)

A synonym for SendTo(addr, port, INET_NULL_INTERFACEID, msg, sendFlags).

SendTo

INET_ERROR SendTo(
  IPAddress addr,
  uint16_t port,
  InterfaceId intfId,
  Weave::System::PacketBuffer *msg,
  uint16_t sendFlags
)

Send a UDP message to the specified destination address.

 If possible, then this method sends the UDP message \c msg to the
 destination \c addr (with \c intfId used as the scope
 identifier for IPv6 link-local destinations) and \c port with the
 transmit option flags encoded in \c sendFlags.

 Where (sendFlags & kSendFlag_RetainBuffer) != 0, calls
 Weave::System::PacketBuffer::Free on behalf of the caller, otherwise this
 method deep-copies \c msg into a fresh object, and queues that for
 transmission, leaving the original \c msg available after return.

Details
Parameters
[in] addr
the destination IP address
[in] port
the destination UDP port
[in] intfId
an optional network interface indicator
[in] msg
the packet buffer containing the UDP message
[in] sendFlags
optional transmit option flags
Return Values
INET_NO_ERROR
success: msg is queued for transmit.
INET_ERROR_NOT_IMPLEMENTED
system implementation not complete.
INET_ERROR_WRONG_ADDRESS_TYPE
the destination address and the bound interface address do not have matching protocol versions or address type.
INET_ERROR_MESSAGE_TOO_LONG
msg does not contain the whole UDP message.
INET_ERROR_OUTBOUND_MESSAGE_TRUNCATED
On some platforms, only a truncated portion of msg was queued for transmit.
other
another system or platform error