MFC ADDP Discovery Sample

Introduction

This sample demonstrates how to write an MFC application to discover and configure devices located on a network using the ADDP library.

For the purpose of this demonstration, the sample application opens a handle to the ADDP library and uses that handle to discover all device servers located on the network. Additionally, the sample uses the ADDP library to perform actions on individual devices, such as configuring its network settings, displaying additional configuration information, and rebooting the device.

Device Server Setup

This sample does not require the device server be configured in any particular way. The device must simply be turned on and connected to a network.

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

Select File > Open Workspace... from the main menu.

Change Files of type: to Projects (.dsp).

Locate and open the .dsp file for this sample.

Select Build > Rebuild All menu items to compile the sample.

Step-by-Step

1. Open an ADDP handle

Any interaction with the ADDP library must begin by calling the ADDPOpen function.
addp_handle_t handle = ADDPOpen(ADDP_VENDOR_ID_DIGI);
Calling ADDPOpen establishes a new session with the ADDP library, and returns a handle of type addp_handle_t that is needed for all of the other ADDP library APIs.

For each successful call to ADDPOpen there must also be a call to ADDPClose to close the ADDP session and invalidate the addp_handle_t (see step 6).

2. Discover devices

After calling ADDPOpen and verifying the handle returned is valid, a device search may be started. The ADDP library provides two different types of device search mechanisms, synchronous and asynchronous. This sample application demonstrates both.

The first mechanism is synchronous, whereby the API used to start the device search does not return until an entire search has completed. The sample calls ADDPStartSyncSearch.

The ADDPStartSyncSearch uses two separate timeout values to determine when the device search should terminate. The first timeout value is the maximum amount of time to wait between search responses received from devices, and the second is the maximum time the entire search should ever take. The ADDPStartSyncSearch API uses default values for these two timeouts. The ADDPStartSyncSearchEx function may be used to specify alternative timeout values.

The second search search mechanism is asynchronous. The asynchronous search APIs return immediately, and use one of three mechanisms to notify the caller that search results have been received. The three notification mechanisms are: send a window an application defined message, call an application defined callback function, or signal an event. The sample uses the ADDPStartAsyncSearchMessage API.

The ADDPStartAsyncSearchMessage takes as parameters the addp_handle_t returned from ADDPOpen, a HWND window handle, a application defined window message to be sent to that window, and optionally a void pointer that will be sent as the LPARAM of the window message. The ADDP library notifies the sample application that search responses have been received by sending the window specified the application defined message. Note that not every response results in the window message being sent.

The other two asynchronous search APIs are ADDPStartAsyncSearchCallback, and ADDPStartAsyncSearchEvent.

After completing a call to ADDPStartSyncSearch or when being notified asynchronously that there are search results to be retrieved, the sample gets the results with the following code:
addp_device_info_t DevInfo = {0};

while (ADDPGetSearchResultCount(handle) > 0)
{
   ADDPGetSearchResults(handle, &DevInfo, 1);
}
ADDPGetSearchResultCount returns the current number of results available to be retrieved, and the ADDPGetSearchResults function is used to copy search results into a storage space defined by the application. For each device discovered on the network, a addp_device_info_t will be returned. See the ADDP library header file addp.h for the current definition of the addp_device_info_t data structure.

When a search is complete, or to stop an active asynchronous search the sample application calls ADDPStopSearch.

3. Configure network settings

The sample provides a means to configure the network settings of a device. The settings that may be configured are DHCP mode, IP address, subnet mask, and default gateway address.

To change the DHCP mode, the sample calls:
ADDPSetDHCP(handle,
            MACAddress,
            DHCPMode,
            Password);  
Where handle is the addp_handle_t returned by ADDPOpen, MACAddress is the MAC address of the device you wish to change the DHCP mode on, DHCPMode is either ADDP_DHCP_MODE_ENABLED or ADDP_DHCP_MODE_DISABLED, and Password is the root user's password for the devices.

To configure a static IP address, subnet mask, and default gateway on a device, the sample application uses the ADDPSetNetwork API.
ADDPSetNetwork(handle,
               MACAddress,
               IPAddress,
               SubnetMask,
               DefaultGateway,
               Password);
Here again, handle is the handle returned by ADDPOpen, and MACAddress is the MAC address of the device to configure. The next three parameters, IPAddress, SubnetMask, and DefaultGateway are IN_ADDR variables defining the static IP address, subnet mask, and default gateway to assign. Finally, Password is the password for the root user on the device.

Note that the device should be rebooted for these changes to take affect.

4. Get device information

Device information, like that retrieved from conducting a search, can be gotten from an individual device. The ADDP library provides the following API to process that request:
addp_device_info_t DevInfo = {0};

ADDPGetDeviceInfo(handle,
               MACAddress,
               &DevInfo);
Similar to the network configuration APIs, ADDPGetDeviceInfo takes as parameters the addp_handle_t returned from ADDPOpen and the MAC address of the device to retrieve information from. The caller must also provide space to copy the addp_device_info_t data to as the DevInfo parameter.

5. Reboot a device

The ADDPRebootDevice function can be used to cause a device to perform a reboot. ADDPRebootDevice takes as parameters the addp_handle_t returned from ADDPOpen and the MAC address of the device to reboot. The reboot operation also requires the device's root user password, which is sent as the third parameter.

The sample also provides the following bit of code:
addp_device_info_t DevInfo = {0};
int Iterations = 0;

while ((ADDP_SUCCESS != ADDPGetDeviceInfo(handle,
                                          MACAddress,
                                          &DevInfo))
       &&
       (Iterations < MAX_ITERATIONS))
{
   Sleep(RETRY_TIME);
   Iterations++;
}
which is used to discover when a rebooting device comes back online. The ADDPGetDeviceInfo function can be used as a sort of "ping" operation, where a return value of ADDP_SUCCESS would indicate that the device has rebooted and can be communicated with.

6. Close the ADDP handle

When the ADDP handle returned by ADDPOpen is not longer needed, it must be closed in order to invalidate the session and free any resources the ADDP library may have allocated. Do this by calling ADDPClose which takes only the addp_handle_t you wish to close as a parameter.

File List

Keywords

ADDPOpen, addp_handle_t, ADDPClose, addp_device_info_t, ADDPStartSyncSearch, ADDPStartSyncSearchEx, ADDPStartAsyncSearchMessage, ADDPStartAsyncSearchCallback, ADDPStartAsyncSearchEvent, ADDPGetSearchResultCount, ADDPGetSearchResults, ADDPStopSearch, ADDPSetDHCP, ADDPSetNetwork, ADDPGetDeviceInfo, ADDPRebootDevice

Digi International Inc.

11001 Bren Road E. Minnetonka, MN 55343
PH: (952) 912-3444 or 877-912-3444
FX: (952) 912-4952