UDP Manual

Table of Contents

• About
• NetworkUdpInterface
• NetworkUdpServerInterface
• NetworkUdpSenderInterface
• NetworkUdpChannelInterface
• Further Reading

About

The User Datagram Protocol allows to send messages across networks without connections. The maxon::NetworkUdpInterface is used to create a sender to send UDP messages or to create a server to receive messages.

Note

The UDP interface uses an AioService. See maxon::AioServiceInterface.

NetworkUdpInterface

The maxon::NetworkUdpInterface provides these functions:

• maxon::NetworkUdpInterface::CreateUdpServer(): Returns a new UDP server.
• maxon::NetworkUdpInterface::CreateUdpSender(): Returns a new UDP sender.
• maxon::NetworkUdpInterface::CreateUdpChannel(): Returns a new UDP channel.

NetworkUdpServerInterface

The maxon::NetworkUdpServerInterface controls an UDP server that can receive UDP data:

• maxon::NetworkUdpServerInterface::Start(): Starts the server.
• maxon::NetworkUdpServerInterface::Stop(): Stops the server.
• maxon::NetworkUdpServerInterface::IsStopped(): Returns true if the server is stopped.
• maxon::NetworkUdpServerInterface::Send(): Sends the given data via UDP.
• maxon::NetworkUdpServerInterface::GetIoService(): Returns the assigned AioServiceRef.
• maxon::NetworkUdpServerInterface::GetJobQueue(): Returns the used job queue.

  // This example starts an UDP server. The behaviour on handling
  // incoming data is defined with the given callback function.
 
  // create AioServiceRef
  g_ioService = maxon::AioServiceRef::Create() iferr_return;
  g_ioService.Start() iferr_return;
 
  // create and start server
  auto localAddr = maxon::NetworkIpAddrPort(maxon::WILDCARD_IPV4_ADDRESS, 1000);
  g_udpServer = maxon::NetworkUdpInterface::CreateUdpServer(localAddr, UDPCallback, g_ioService) iferr_return;
  g_udpServer.Start() iferr_return;

// This example shows a callback function that defines the behaviour of an UDP server for handling incoming data.
 
static maxon::Result<void> UDPCallback(maxon::Result<void> result, maxon::AioBuffer receivedData, maxon::NetworkIpAddrPort sender)
{
  iferr_scope;
 
  // print the remote address
  DiagnosticOutput("Sender: @", sender);
 
  // print the received data
  const maxon::String message { receivedData };
  DiagnosticOutput("Message: @", message);
 
  return maxon::OK;
}

NetworkUdpSenderInterface

The maxon::NetworkUdpSenderInterface allows to send data via UDP to a remote machine.

• maxon::NetworkUdpSenderInterface::Send(): Enqueues an asynchronous send request to send data.
• maxon::NetworkUdpSenderInterface::GetIoService(): Returns the assigned AioServiceRef.
• maxon::NetworkUdpSenderInterface::GetJobQueue(): Returns the used job queue.

  // This example sends some data to a remote address using UDP.
 
  // prepare AioServiceRef
  const maxon::AioServiceRef service = maxon::AioServiceRef::Create() iferr_return;
  service.Start() iferr_return;
 
  // create sender
  const maxon::NetworkUdpSenderRef sender = maxon::NetworkUdpInterface::CreateUdpSender(maxon::PROTOCOL::IPV4, service) iferr_return;
 
  // prepare message
  maxon::CString   messageCStr("Test Message");
  maxon::AioBuffer buffer;
  for (const maxon::Char c : messageCStr)
  {
    iferr (buffer.Append(c))
      err.DbgStop();
  }
 
  // send message
  sender.Send(std::move(buffer), remoteAdress) iferr_return;

NetworkUdpChannelInterface

maxon::NetworkUdpChannelInterfac represents an asynchronous UDP channel that can both receive data and send data:

• maxon::NetworkUdpChannelInterface::Receive(): Enqueues an asynchronous receive request.
• maxon::NetworkUdpChannelInterface::Send(): Enqueues an asynchronous send request to send data.
• maxon::NetworkUdpChannelInterface::GetIoService(): Returns the assigned AioServiceRef.
• maxon::NetworkUdpChannelInterface::GetJobQueue(): Returns the used job queue.

  // This example creates an UDP channel that allows to send and receive data.
  // The behaviour on receiving data is defined with the given callback.
 
  // prepare AioServiceRef
  g_channelIoService = maxon::AioServiceRef::Create() iferr_return;
  g_channelIoService.Start() iferr_return;
 
  // create channel
  auto localAddr = maxon::NetworkIpAddrPort(maxon::WILDCARD_IPV4_ADDRESS, 1001);
  g_udpChannel = maxon::NetworkUdpInterface::CreateUdpChannel(localAddr, g_channelIoService) iferr_return;
  g_udpChannel.Receive(ChannelReceiveCallback) iferr_return;

// This callback function for an UDP channel prints the received message.
 
static maxon::Result<void> ChannelReceiveCallback(maxon::Result<void>, maxon::AioBuffer buf, maxon::NetworkIpAddrPort sender)
{
  iferr_scope;
 
  // print the remote address
  DiagnosticOutput("Sender: @", sender);
 
  // print the received data
  const maxon::String message { buf };
  DiagnosticOutput("Message: @", message);
 
  return maxon::OK;
}

Further Reading

• Network
• Delegates