/*****************************************************************************
*
* Copyright (c) Digi International Inc. 2003. All Rights Reserved
*
* Digi provides this document "as is," without warranty of any kind,
* either expressed or implied, including, but not limited to, the implied
* warranties of fitness or merchantability for a particular purpose. Digi
* may make improvements and/or changes in this document or in the product(s)
* and/or the program(s) described in this document at any time.
*
* This document could include technical inaccuracies or typographical errors.
* Changes are periodically made to the information herein; these changes may
* be incorporated in new editions of the publication.
*
* Digi International Inc.
* 11001 Bren Road East
* Minnetonka, MN 55343, USA
* Tel: +1 (952) 912-3444
* Fax: +1 (952) 912-4952
* http://www.digi.com/
*
*****************************************************************************/

#if !defined(ADDP_H_INCLUDED)
#define ADDP_H_INCLUDED

#if defined(WIN32)

#if _MSC_VER > 1000
#pragma once
#endif /* _MSC_VER > 1000 */

#if !defined(_MT)
#error This library requires multithreaded run-time libraries.  Use one of the following compiler switches: /MD, /MDd, /MT, or /MTd.
#else
	#if defined(_DLL)
		#if defined(_DEBUG)
			/* /MDd Debug Dynamic Link (DLL) MSVCRTD */
			#pragma comment(lib, "addpdld.lib")
		#else
			/* /MD Dynamic Link (DLL) MSVCRT */
			#pragma comment(lib, "addpdl.lib")
		#endif /* defined(_DEBUG) */
	#else
		#if defined(_DEBUG)
			/* /MTd Debug Static MultiThread LIBCMTD */
			#pragma comment(lib, "addpsld.lib")
		#else
			/* /MT Static MultiThread LIBCMT */
			#pragma comment(lib, "addpsl.lib")
		#endif /* defined(_DEBUG) */
	#endif /* defined(_DLL) */
#endif /* !defined(_MT) */

#if !defined(ADDP_NO_WINSOCK)
#include <winsock.h>
#pragma comment(lib, "wsock32.lib")
#endif /* !defined(ADDP_NO_WINSOCK) */

#include <pshpack8.h>

#endif /*  defined(WIN32) */

#if defined(__cplusplus)
extern "C" {
#endif


/*
 * ADDP Open/Close Functions, Types, and Definitions
 *
 * The following functions, types, and definitions are used to open an ADDP
 * session and acquire an ADDP handle.  They are also used to subsequently close
 * an ADDP session and release the ADDP handle.
 *
 * The ADDPOpen operation must be performed before any other ADDP function call
 * can be made.  For every successful ADDPOpen call, there must also be a
 * corresponding ADDPClose call to close the ADDP handle allocated by the open
 * and release any resources associated with that ADDP session.
 */

/* Vendor ID assigned to Digi International Inc. */
#define ADDP_VENDOR_ID_DIGI		0x44494749

/* ADDP handle type definition */
typedef void* addp_handle_t;

/*
 * ADDPOpen
 *
 * The ADDPOpen function creates a new ADDP session and returns a handle that
 * can be used with subsequent ADDP API calls.
 *
 * Parameters
 *
 *   vendor_id
 *     [in] Unique vendor identifier.
 *
 * Return Values
 *
 *   If no error occurs, the return value is an open handle to a new ADDP
 *   session.
 *
 *   If the function fails, the return value is NULL.
 *
 * Remarks
 *
 *   For every successful ADDPOpen call there must be a corresponding call to
 *   ADDPClose to close the ADDP handle.
 *
 *   The ADDPOpen function must be called before any other ADDP functions can be
 *   used.
 *
 *   Vendor identifiers are unique four byte values assigned by Digi
 *   International Inc.
 */
addp_handle_t ADDPOpen(const u_long vendor_id);

/*
 * ADDPClose
 *
 * The ADDPClose function closes an ADDP session, releases any resources
 * associated with the ADDP session, and invalidates the ADDP handle.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 * Return Values
 *
 *   None.
 *
 * Remarks
 *
 *   ADDPClose invalidates the specified handle rendering it unusable for any
 *   further ADDP function calls.
 *
 *   Any active searches are terminated and the search results are destroyed.
 */
void ADDPClose(const addp_handle_t handle); 


/*
 * ADDP Error Functions, Types, and Definitions
 *
 * The following functions, types, and definitions are used as return values for
 * many of the ADDP functions, and to indicate error conditions and messages
 * associated with performing ADDP commands.
 */

/* ADDP API return values */
#define ADDP_SUCCESS							0
#define ADDP_FAIL								-1

/* ADDP protocol error codes */
#define ADDP_ERROR_SUCCESS						0
#define ADDP_ERROR_AUTHENTICATON_FAILED			1
#define ADDP_ERROR_UNIT_HAS_ADDRESS				2
#define ADDP_ERROR_INVALID_VALUE				3
#define ADDP_ERROR_INVALID_DATA					4
#define ADDP_ERROR_UNSUPPORTED_COMMAND			5

/*
 * ADDPGetLastError
 *
 * ADDPGetLastError returns the ADDP error code associated with the last action
 * performed.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 * Return Values
 *
 *   If the function succeeds, ADDPGetLastError will return one of the
 *   ADDP_ERROR_xxxx values defined above.
 *
 *   Otherwise, it will return ADDP_FAIL.
 *
 * Remarks
 *
 *   To obtain an error string, use ADDPGetLastErrorMessage.
 *
 *   The last error value is maintained on a per ADDP API function call basis.
 *   Any previous error values may be overwritten by subsequent API calls.
 */
int ADDPGetLastError(const addp_handle_t handle);

/*
 * ADDPGetLastErrorMessage
 *
 * ADDPGetLastErrorMessage returns the ADDP error string associated with the
 * last action performed.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   message
 *     [out] A pointer to a character array buffer for the message.
 *
 *   max_message_length
 *     [in] Specifies the maximum number of characters buffer points to
 *          (including the NULL terminator).
 *
 * Return Values
 *
 *   If the function succeeds, the return value is ADDP_SUCCESS.
 *
 *   Otherwise, the return value is ADDP_FAIL.
 *
 * Remarks
 *
 *   To obtain the last error code, use ADDPGetLastError.
 *
 *   The last error message is maintained on a per ADDP API function call basis.
 *   Any previous error messages may be overwritten by subsequent API calls.
 */
int ADDPGetLastErrorMessage(const addp_handle_t handle, char * const message, const size_t max_message_length);


/*
 * ADDP Device Info Functions, Types, and Definitions
 *
 * The following functions, types, and definitions are used to perform ADDP
 * device searches and to return information about the devices found.
 */

/* ADDP device info version definitions */
#define ADDP_VERSION_0100										0x0100
#define ADDP_CURRENT_VERSION									ADDP_VERSION_0100

/* ADDP MAC address definitions */
#define ADDP_MAC_ADDRESS_LENGTH									6
typedef u_char addp_mac_address_t[ADDP_MAC_ADDRESS_LENGTH];

/* IN_ADDR definition */
#if !defined(IN_ADDR)
typedef struct in_addr IN_ADDR;
#endif /* !defined(IN_ADDR) */

/*
 * ADDP valid_data member bit flag values
 * 
 * These values are used in conjunction with the addp_device_info_t valid_data
 * structure member to indicate which of the other structure members have been
 * filled in with valid data.  Valid_data may be set to any of the following
 * values combined together using the bitwise OR (|) operator.
 */
#define ADDP_DEVICE_INFO_VALID_DATA_MAC_ADDRESS					0x00000001
#define ADDP_DEVICE_INFO_VALID_DATA_IP_ADDRESS					0x00000002
#define ADDP_DEVICE_INFO_VALID_DATA_SUBNET_MASK					0x00000004
#define ADDP_DEVICE_INFO_VALID_DATA_GATEWAY_ADDRESS				0x00000008
#define ADDP_DEVICE_INFO_VALID_DATA_DNS_ADDRESS					0x00000010
#define ADDP_DEVICE_INFO_VALID_DATA_DHCP_MODE					0x00000020
#define ADDP_DEVICE_INFO_VALID_DATA_REALPORT_PORT				0x00000040
#define ADDP_DEVICE_INFO_VALID_DATA_NAME						0x00000080
#define ADDP_DEVICE_INFO_VALID_DATA_DOMAIN						0x00000100
#define ADDP_DEVICE_INFO_VALID_DATA_HARDWARE_TYPE				0x00000200
#define ADDP_DEVICE_INFO_VALID_DATA_HARDWARE_REVISION			0x00000400
#define ADDP_DEVICE_INFO_VALID_DATA_FIRMWARE_VERSION			0x00000800
#define ADDP_DEVICE_INFO_VALID_DATA_PRODUCT_NAME				0x00001000
#define ADDP_DEVICE_INFO_VALID_DATA_PORT_COUNT					0x00002000
#define ADDP_DEVICE_INFO_VALID_DATA_ADVISORY					0x00004000
#define ADDP_DEVICE_INFO_VALID_DATA_WIRELESS					0x00008000

/* ADDP maximum string and buffer length (including NULL terminator) */
#define ADDP_MAX_STRING_LENGTH									255
#define ADDP_MAX_STRING_BUFFER_LENGTH							(ADDP_MAX_STRING_LENGTH + 1)

/* ADDP default RealPort port number */
#define ADDP_REALPORT_PORT_DEFAULT								771

/* ADDP dhcp_mode values */
#define ADDP_DHCP_MODE_DISABLED									0
#define ADDP_DHCP_MODE_ENABLED									1

/* ADDP advisory values */
#define ADDP_ADVISORY_NONE										0
#define ADDP_ADVISORY_MISCONFIGURED								1

/* 
 * ADDP wireless valid_data member bit flag values
 *
 * These values are used in conjunction with the addp_wireless_info_t valid_data
 * structure member to indicate which of the other structure members have been
 * filled in with valid data.  Valid_data may be set to any of the following
 * values combined together using the bitwise OR (|) operator.
 */
#define ADDP_WIRELESS_INFO_VALID_DATA_SSID						0x00000001
#define ADDP_WIRELESS_INFO_VALID_DATA_AUTO_SSID					0x00000002
#define ADDP_WIRELESS_INFO_VALID_DATA_AUTHENTICATION_MODE		0x00000004
#define ADDP_WIRELESS_INFO_VALID_DATA_ENCRYPTION_MODE			0x00000008
#define ADDP_WIRELESS_INFO_VALID_DATA_ENCRYPTION_KEY			0x00000010
#define ADDP_WIRELESS_INFO_VALID_DATA_COUNTRY_CODE				0x00000020

/* ADDP wireless ssid definitions */
#define ADDP_WIRELESS_MAX_SSID_LENGTH							32

/*
 * NOTE
 *
 * This is a length counted buffer, and does not ensure that even if the data
 * contained in buffer represents an ASCII string, that it is NULL terminated.
 */
typedef struct _addp_wireless_ssid_t
{
	u_char	length;
	u_char	buffer[ADDP_WIRELESS_MAX_SSID_LENGTH];
}
addp_wireless_ssid_t;

/* ADDP wireless auto_ssid values */
#define ADDP_WIRELESS_AUTO_SSID_DISABLED						0
#define ADDP_WIRELESS_AUTO_SSID_ENABLED							1

/* ADDP wireless authentication_mode values */
#define ADDP_WIRELESS_AUTHENTICATION_MODE_OPEN_SYSTEM			0x0001
#define ADDP_WIRELESS_AUTHENTICATION_MODE_SHARED_KEY			0x0002

/* ADDP wireless encryption_mode values */
#define ADDP_WIRELESS_ENCRYPTION_MODE_NONE						1
#define ADDP_WIRELESS_ENCRYPTION_MODE_WEP40						2
#define ADDP_WIRELESS_ENCRYPTION_MODE_WEP128					3

/* ADDP wireless encryption_key definitions */
#define ADDP_WIRELESS_MAX_ENCRYPTION_KEY_LENGTH					13

/*
 * NOTE
 *
 * This is a length counted buffer, and does not ensure that even if the data
 * contained in buffer represents an ASCII string, that it is NULL terminated.
 */
typedef struct _addp_wireless_encryption_key_t
{
	u_char	length;
	u_char	buffer[ADDP_WIRELESS_MAX_ENCRYPTION_KEY_LENGTH];
}
addp_wireless_encryption_key_t;

/* ADDP wireless info structure */
typedef struct _addp_wireless_info_t
{
	size_t									size;					/* the sizeof this structure */
	u_long									valid_data;				/* what members contain valid data */
	addp_wireless_ssid_t					ssid;
	u_short									auto_ssid;
	u_short									authentication_mode;
	u_short									encryption_mode;
	addp_wireless_encryption_key_t	encryption_key;
	u_short									country_code;
}
addp_wireless_info_t;

#define ADDP_WIRELESS_INFO_SIZE	(sizeof(addp_wireless_info_t))

/* ADDP device info structure */
typedef struct _addp_device_info_t
{
	size_t						size;								/* the sizeof this structure */
	u_long						version;

	IN_ADDR						interface_address;					/* the local interface this device was found on */

	u_long						vendor_id;

	u_long						valid_data;							/* what members contain valid data */

	addp_mac_address_t			mac_address;
	IN_ADDR						ip_address;
	IN_ADDR						subnet_mask;
	IN_ADDR						gateway_address;
	IN_ADDR						dns_address;
	u_char						dhcp_mode;

	u_short						realport_port;

	char						name[ADDP_MAX_STRING_BUFFER_LENGTH];
	char						domain[ADDP_MAX_STRING_BUFFER_LENGTH];

	u_char						hardware_type;
	u_char						hardware_revision;
	char						firmware_version[ADDP_MAX_STRING_BUFFER_LENGTH];
	char						product_name[ADDP_MAX_STRING_BUFFER_LENGTH];
	u_char						port_count;
	
	u_short						advisory;

	addp_wireless_info_t		wireless_info;
}
addp_device_info_t;

#define ADDP_DEVICE_INFO_T_SIZE	(sizeof(addp_device_info_t))

/* INFINITE timeout period definition */
#if !defined(INFINITE)
#define INFINITE	0xFFFFFFFF
#endif

/* ADDP default synchronous search timeout values */
#define ADDP_TIMEOUT_INTERPACKET_DEFAULT		5000		/* 5 seconds */
#define ADDP_TIMEOUT_TOTAL_DEFAULT				60000		/* 1 minute */

/* CALLBACK calling convention definition */
#if !defined(CALLBACK)
#define CALLBACK	__stdcall
#endif /* !defined(CALLBACK) */

/*
 * ADDPStartSyncSearch
 *
 * The ADDPStartSyncSearch function is used to start a synchronous device
 * search.  The function call does not return until the search is complete.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 * Return Values
 *
 *   If the function succeeds, the return value is the number of devices found,
 *   which could be zero (0).
 *
 *   Otherwise, the function returns ADDP_FAIL.
 *
 * Remarks
 *
 *   Two different timeout values are used to determine when the search should
 *   terminate.
 *
 *   The first is an inter-packet timeout, which specifies the maximum time
 *   period to wait between receiving search responses from devices before
 *   stopping the search and returning to the caller.  If search results are
 *   received before this timeout period elapses, the timer is reset.
 *
 *   The second timeout value specifies the maximum amount of time the search
 *   should ever take.  This timer is started when the search is started, and is
 *   never reset.  If the time period elapses, the search is terminated and the
 *   API returns to the caller.
 *
 *   Calling ADDPStartSyncSearch(handle) is the same as calling
 *   ADDPStartSyncSearchEx(handle,
 *                        ADDP_TIMEOUT_INTERPACKET_DEFAULT,
 *                        ADDP_TIMEOUT_TOTAL_DEFAULT);
 *
 *   You may call ADDPStopSearch after ADDPStartSyncSearch has returned, but it
 *   is not required.
 *
 *   To retrieve the search results, call ADDPGetSearchResults.
 */
int ADDPStartSyncSearch(const addp_handle_t handle);

/*
 * ADDPStartSyncSearchEx
 *
 * The ADDPStartSyncSearchEx function is used to start a synchronous device
 * search.  The function call does not return until the search is complete.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   interpacket_timeout
 *     [in] Maximum time period in milliseconds to wait between receipt of
 *          search responses before terminating search.
 *
 *   total_timeout
 *     [in] Maximum time period in milliseconds the entire search may take
 *          before terminating.
 *
 * Return Values
 *
 *   If the function succeeds, the return value is the number of devices found,
 *   which could be zero (0).
 *
 *   Otherwise, the function returns ADDP_FAIL.
 *
 * Remarks
 *
 *   This function is identical to ADDPStartSyncSearch, except it allows you to
 *   specify the inter-packet and total timeout values used to terminate the
 *   search.  This allows for extra flexibility in performing synchronous
 *   searches, and fine tuning based on network topologies.
 *
 *   You may call ADDPStopSearch after ADDPStartSyncSearchEx has returned, but
 *   it is not required.
 *
 *   To retrieve the search results, call ADDPGetSearchResults.
 */
int ADDPStartSyncSearchEx(const addp_handle_t handle, const u_long interpacket_timeout, const u_long total_timeout);

/*
 * addp_search_callback_t
 *
 * An addp_search_callback_t is a application defined callback function that
 * can be used to retrieve and process ADDP search results.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   context
 *     [in/out] Application defined callback context value.
 *
 * Return Values
 *
 *   None.
 *
 * Remarks
 *
 *   The addp_search_callback_t application defined function is used with the
 *   ADDPStartAsyncSearchCallback API.  It is called to notify the application
 *   that search results have been received and are ready to be retrieved by
 *   calling ADDPGetSearchResults.
 */
typedef void (CALLBACK *addp_search_callback_t)(const addp_handle_t handle, void * context);

/*
 * ADDPStartAsyncSearchCallback
 *
 * The ADDPStartAsyncSearchCallback function starts an asynchronous device
 * search.  This function call returns immediately, and the application is
 * notified that search results are available via an application defined
 * callback function mechanism.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   callback
 *     [in] Pointer to application defined callback function used to notify that
 *          search results are waiting to be retrieved.
 *
 *   context
 *     [in] Application defined context value passed to callback function.
 *
 * Return Values
 *
 *   If the function succeeds, the return value is ADDP_SUCCESS.
 *
 *   Otherwise, the function returns ADDP_FAIL.
 *
 * Remarks
 *
 *   The ADDP search engine will notify the application that there are results
 *   to be retrieved by calling the addp_search_callback_t function.  Not every
 *   search response received will generate a call to the application defined
 *   callback.  It is left up to the application to retrieve all of the
 *   results available.
 *
 *   You must call ADDPStopSearch after calling ADDPStartAsyncSearchCallback to
 *   stop the search and to prevent any future result notifications.
 *
 *   To get the number of search results available to be retrieved, call
 *   ADDPGetSearchResultCount.
 *
 *   To retrieve the search results, call ADDPGetSearchResults.
 */
int ADDPStartAsyncSearchCallback(const addp_handle_t handle, addp_search_callback_t const callback, const void * const context);

/*
 * ADDPStartAsyncSearchMessage
 *
 * The ADDPStartAsyncSearchMessage function starts an asynchronous device
 * search.  This function call returns immediately, and the application is
 * notified that search results are available via an application defined
 * message being sent a window.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   hwnd
 *     [in] Handle of the window to send the message (msg) to notifying it that
 *          search results are waiting to be retrieved.
 *
 *   msg
 *     [in] Application defined message sent to the window defined by hwnd.
 *          This message should be in the WM_APP range of message values, and
 *          defined as (WM_APP + X) where X is an integer value, or a
 *          registered message value returned from RegisterWindowMessage.
 *
 *   context
 *     [in] Application defined value passed to the window requesting search
 *          result notification as LPARAM for the message defined by msg.
 *
 * Return Values
 *
 *   If the function succeeds, the return value is ADDP_SUCCESS.
 *
 *   Otherwise, the function returns ADDP_FAIL.
 *
 * Remarks
 *
 *   The ADDP search engine will notify the application that there are results
 *   to be retrieved by sending a message (msg) to a window (hwnd).  Not every
 *   search response received will generate a message to be sent.  It is left up
 *   to the application to retrieve all of the results available.
 *
 *   You must call ADDPStopSearch after calling ADDPStartAsyncSearchMessage to
 *   stop the search and to prevent any future result notifications.
 *
 *   To get the number of search results available to be retrieved, call
 *   ADDPGetSearchResultCount.
 *
 *   To retrieve the search results, call ADDPGetSearchResults.
 */
int ADDPStartAsyncSearchMessage(const addp_handle_t handle, const HWND hwnd, const UINT msg, const void * const context);

/*
 * ADDPStartAsyncSearchEvent
 *
 * The ADDPStartAsyncSearchEvent function starts an asynchronous device
 * search.  This function call returns immediately, and the application is
 * notified that search results are available via an application defined
 * event being set to a signaled state.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   event
 *     [in] Handle to the application defined event used to signal that search
 *          results are waiting to be retrieved.  This handle should be created
 *          by calling CreateEvent, or obtained from a CEvent object.
 *
 * Return Values
 *
 *   If the function succeeds, the return value is ADDP_SUCCESS.
 *
 *   Otherwise, the function returns ADDP_FAIL.
 *
 * Remarks
 *
 *   The ADDP search engine will notify the application that there are results
 *   to be retrieved by setting the event to a signaled state.  Not every
 *   search response received will cause the event to be signaled.  It is left
 *   up to the application to retrieve all of the results available.
 *
 *   You must call ADDPStopSearch after calling ADDPStartAsyncSearchEvent to
 *   stop the search and to prevent any future result notifications.
 *
 *   To get the number of search results available to be retrieved, call
 *   ADDPGetSearchResultCount.
 *
 *   To retrieve the search results, call ADDPGetSearchResults.
 */
int ADDPStartAsyncSearchEvent(const addp_handle_t handle, const HANDLE event);

/*
 * ADDPGetSearchResultCount
 *
 * This function returns the number of search results available to be retrieved
 * at any given time.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 * Return Values
 *
 *   If the function succeeds, the number of search results available is
 *   returned, which could be zero (0).
 *
 *   Otherwise, the function returns ADDP_FAIL.
 */
int ADDPGetSearchResultCount(const addp_handle_t handle);

/*
 * ADDPGetSearchResults
 *
 * This function is used to retrieve search results received from devices
 * discovered by using one of the search APIs defined above.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   results
 *     [out] A pointer to addp_device_info_t structures to be filled in with
 *           search results.
 *
 *   max_results_count
 *     [in] Maximum number of addp_device_info_t structures that results points
 *          to.
 *
 * Return Values
 *
 *   If the function succeeds, the number of search results copied into the
 *   results array is returned.  This number may be less than max_results_count.
 *   A return value less than max_results_count, or zero (0) indicates there are
 *   no more search results available.
 *
 *   Otherwise, the function returns ADDP_FAIL.
 */
int ADDPGetSearchResults(const addp_handle_t handle, addp_device_info_t results[], const size_t max_result_count);

/*
 * ADDPStopSearch
 *
 * This function stops any active asynchronous search and future search result
 * notifications.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 * Return Values
 *
 *   None.
 *
 * Remarks
 *
 *   You cannot call this function to cancel a synchronous search started by
 *   calling ADDPStartSyncSearch or ADDPStartSyncSearchEx.
 *
 *   This function does not cause any search results to be destroyed, thus you
 *   can still use ADDPGetSearchResults even after having stopped a search.
 */
void ADDPStopSearch(const addp_handle_t handle);


/*
 * ADDP Get/Set/Action Functions
 *
 * The following functions define APIs for getting or setting configuration
 * information, or performing actions on individual devices.
 */

/*
 * ADDPGetDeviceInfo
 *
 * This function queries a single device for its device information.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   mac_address
 *     [in] The MAC address of the device to query.
 *
 *   device_info
 *     [out] A pointer to an addp_device_info_t structure to receive the
 *           information.
 *
 * Return Values
 *
 *   If the function succeeds, the return value is ADDP_SUCCESS.
 *
 *   Otherwise, the function returns ADDP_FAIL.
 *
 * Remarks
 *
 *   ADDPGetLastError and ADDPGetLastErrorMessage can be used to retrieve more
 *   specific error details.
 */
int ADDPGetDeviceInfo(const addp_handle_t handle, const addp_mac_address_t mac_address, addp_device_info_t * const device_info);

/*
 * ADDPRebootDevice
 *
 * The ADDPRebootDevice function is used to cause an individual device to
 * reboot.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   mac_address
 *     [in] The MAC address of the device to reboot.
 *
 *   password
 *     [in] The device's root user password.  For devices that do not have
 *          a password this can be an empty string ("") but not NULL.
 *
 * Return Values
 *
 *   If the function succeeds, the return value is ADDP_SUCCESS.
 *
 *   Otherwise, the function returns ADDP_FAIL.
 *
 * Remarks
 *
 *   ADDPGetLastError and ADDPGetLastErrorMessage can be used to retrieve more
 *   specific error details.
 */
int ADDPRebootDevice(const addp_handle_t handle, const addp_mac_address_t mac_address, const char * const password);

/*
 * ADDPSetNetwork
 *
 * This function is used to configure network settings for a particular device.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   mac_address
 *     [in] The MAC address of the device to configure.
 *
 *   ip_address
 *     [in] The IP address to be assigned to the device.
 *
 *   subnet_mask
 *     [in] The subnet mask to be assigned to the device.
 *
 *   gateway_address
 *     [in] The gateway address to be assigned to the device.
 *
 *   password
 *     [in] The device's root user password.  For devices that do not have
 *          a password this can be an empty string ("") but not NULL.
 *
 * Return Values
 *
 *   If the function succeeds, the return value is ADDP_SUCCESS.
 *
 *   Otherwise, the function returns ADDP_FAIL.
 *
 * Remarks
 *
 *   Using ADDPSetNetwork to configure a device's network settings causes the
 *   DHCP mode of the device to change to ADDP_DHCP_MODE_DISABLED.  Use
 *   ADDPSetDHCP to enable DHCP.
 *
 *   ADDPGetLastError and ADDPGetLastErrorMessage can be used to retrieve more
 *   specific error details.
 */
int ADDPSetNetwork(const addp_handle_t handle, const addp_mac_address_t mac_address, const IN_ADDR ip_address, const IN_ADDR subnet_mask, const IN_ADDR gateway_address, const char * const password);

/*
 * ADDPSetDHCP
 *
 * The ADDPSetDHCP is used to set the DHCP mode of a particular device.
 *
 * Parameters
 *
 *   handle
 *     [in] The handle successfully created by calling ADDPOpen.
 *
 *   mac_address
 *     [in] The MAC address of the device to configure.
 *   
 *   dhcp_mode
 *     [in] The DHCP mode to assign to the device.  This should be
 *          ADDP_DHCP_MODE_ENABLED or ADDP_DHCP_MODE_DISABLED.
 *
 *   password
 *     [in] The device's root user password.  For devices that do not have
 *          a password this can be an empty string ("") but not NULL.
 *
 * Return Values
 *
 *   If the function succeeds, the return value is ADDP_SUCCESS.
 *
 *   Otherwise, the function returns ADDP_FAIL.
 *
 * Remarks
 *
 *   If you use ADDPSetDHCP to disable DHCP, you should ensure the device has
 *   correct network settings to operate on your network by calling
 *   ADDPSetNetwork.
 *
 *   ADDPGetLastError and ADDPGetLastErrorMessage can be used to retrieve more
 *   specific error details.
 */
int ADDPSetDHCP(const addp_handle_t handle, const addp_mac_address_t mac_address, const u_char dhcp_mode, const char * const password);


#if defined(__cplusplus)
}
#endif

#if defined(WIN32)
#include <poppack.h>
#endif /*  defined(WIN32) */

#endif /* ADDP_H_INCLUDED */