WSA UDP Serial Sample

Introduction

This sample demonstrates how to write a UDP serial application using the Windows Socket Architecture (WSA) to communicate with a device server.

For the purpose of this demonstration, the sample application creates a networking socket it uses to send and receive serial data encapsulated in UDP datagrams from the device server. The device server uses its UDP Serial Client and Server features, and a loopback plug to relay data received on its first port back to the sample application.

Device Server Setup

This sample was designed to operate with the first port on the device server, and requires that the port be configured with UDP Client and Server information. After the device server is configured properly, the port must also have a loopback plug attached to it.

Configure the device server

1. Access the web interface by entering the module’s IP address in a browser’s URL window.
2. Choose Serial Ports from the Configuration menu.
3. Configure the module as a UDP server by doing the following:
   1. Click the UDP tab.
   2. Check Enable UDP Server.
   3. Specify 2101 as the Raw UDP port.
   4. Click Save.
4. Configure the module as a UDP client by doing the following:
   1. Click Enable UDP Client.
   2. Configure a destination by doing the following (1) Supplying the IP address of the PC on which the sample application is installed. (2) Supplying a UDP port of 7777. (3) Ensuring that the Enabled field is checked.
   3. Click Save.
5. Connect the loopback plug to port 1.

How To Build

This sample has been written and tested with Microsoft Visual C++® 6.0. It contains a Developer Studio project file (.dsp), that can be opened in the development environment for editing and compiling.

To build this sample from within Microsoft Visual C++® 6.0

1. Select File > Open Workspace... from the main menu.
2. Change Files of type: to Projects (.dsp).
3. Locate and open the .dsp file for this sample.
4. Select Build > Rebuild All menu items to compile the sample.

Step-by-Step

1.  Initialize Windows Sockets

The following initialization code is found early in the program's main function.

WSABUF WSABuf = {0};
WSAStartup(WINSOCK_VERSION, &WSAData);

Initializing Windows Sockets is critical. Failing to initialize Windows Sockets will cause all other socket function calls to fail.

This sample utilizes Windows Sockets version 2.2. Therefore, the macro WINSOCK_VERSION is defined in the system header file WinSock2.h. An application that calls WSAStartup must call WSACleanup when it is done using the Windows Socket services (see step 7).

2.  Create a local socket

The call to create a socket looks like this:

SOCKET Socket = WSASocket(AF_INET, Type, Protocol,
                          NULL, 0, 0);

Where Type is SOCK_DGRAM and Protocol is IPPROTO_UDP for a blocking, connectionless datagram socket.

3.  Bind to a local port

To bind the socket to a local port, call the following function:

bind(Socket, &SockAddr, sizeof(SockAddr));

Binding to a local port must be done before using the socket to calls like WSASendTo, and is used to associate the currently unnamed socket with a local name.

The SockAddr parameter is the SOCKADDR representation of the local name to bind to. This name consists of an address family (for UDP, always AF_INET), a host address, and a port number.

In this sample, the calls to WSASocket and bind are both done in the function MySocketOpen. Since this sample demonstrates a UDP application, a well-known port (7777) is supplied to the call to MySocketOpen. The same well-known port is also used by the device server as part of its UDP Client destination address information.

4.  Transmit data

Transmitting data is done by calling WSASendTo.

WSASendTo(Socket, &WSABuf,
          1, &LengthSent,
          0, &SockAddr, sizeof(SockAddr),
          NULL, NULL);

To simplify transmitting data, and to hide many of the details associated with the parameters necessary to call WSASendTo, this sample uses its own function named MySocketSendTo.

MySocketSendTo(MySocket, SendData, sizeof(SendData),
               AddressToSendTo, PortToSendTo);

The parameters needed for MySocketSend are: MySocket which is the socket returned from MySocketOpen, SendData which is a pointer to the buffer holding the data to send, SendLength which is the number of bytes SendData points to, and AddressToSendTo and PortToSendTo which provide the IP address and port number of the device server to send the data to. For Digi device servers, the UDP port number for Port 1 is 2101

5.  Receive data

To retrieve data received at the local address, call WSARecvFrom.

WSARecvFrom(Socket, &WSABuf, 1, Length,
            &Flags, &SockAddr, &SockAddrLength,
            NULL, NULL);

With the device server setup with the loopback plug, the data transmitted in the step above will be sent directly back to the sample application.

Like WSASendTo, WSARecvFrom has a large number of parameters, providing great flexibility at the price of adding to its complexity. Also like WSASendTo, the sample provides an alternative function, MySocketRecvFrom that is somewhat easier to use.

MySocketRecvFrom(MySocket,
                 RecvData, &BytesReceived,
                 AddressReceivedFrom,
                 &AddressReceivedFromLength);

The caller to MySocketRecv need only supply the prerequisite MySocket, a buffer RecvData to hold the received data, BytesReceived which specifies the length of RecvData and on return exactly how many bytes were actually copied into the buffer, AddressReceivedFrom which provides space to return a string representation of the IP address and port number of the device server that sent the data, and &AddressReceivedFromLength which specifies the length of AddressReceivedFrom.

6.  Close the socket

Accomplish this task by calling the following two functions:

shutdown(Socket, SD_BOTH);
closesocket(Socket);

When the sample application is done using the socket, the connection it represents must be terminated properly (shutdown) and any resources it may be using should be released (closesocket).

7.  Cleanup

Before exiting the program, call:

WSACleanup();

For every successful call to WSAStartup an application completes, the application must make one call to WSACleanup.

File List

HexDumpData.cpp

HexDumpData.h

MySocket.cpp

MySocket.h

StdAfx.cpp

StdAfx.h

UDPSerial.cpp

UDPSerial.dsp

Keywords

WSASocket; WSASendTo; WSARecvFrom; shutdown; closesocket; WSACleanup