////////////////////////////////////////////////////////////////////////////////
//
// INTEL Corporation Proprietary Information
// Copyright (c) 1995 Intel Corporation
//
// This  software  is supplied under the terms of a license agreement with INTEL
// Corporation  and  may not be used, copied, nor disclosed except in accordance
// with the terms of that agreement.
//
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
//
// $Workfile:   arscli.h  $
// $Revision:   1.6  $
// $Modtime:   19 Sep 1996 19:20:44  $
//
// DESCRIPTION:
//
//		This header file defines the Address Resolution Service's client
//		side interface.  This interface is meant to be used by applications
//		who have a need to map to dynamically assigned address information
//		for a given user (i.e. if the user is connected to the internet via
//		a ISP who uses DHCP to hand out IP addresses.
//
//		The following exported functions are declared in this file:
//
//			ARCreateRegistration()
//			ARDestroyRegistration()
//			ARCreateCallTargetInfo()
//			ARQueryCallTargetInfo()
//			ARDestroyCallTargetInfo()
//			ARGetConfigVal()
//			ARSetConfigVal()
//			ARReleaseStringResult()
//			ARGetHostByAddr()
//
////////////////////////////////////////////////////////////////////////////////

/****************************************************************************
 *
 *	ARS Client Interface 0.005
 *
 ***************************************************************************/

#ifndef ARSCLIENT_H
#define ARSCLIENT_H


#ifndef DllImport
#define DllImport	__declspec( dllimport )
#endif  // DllImport

#ifndef DllExport
#define DllExport	__declspec( dllexport )
#endif	// DllExport

//
// Error Handling Information
//

#include <winerror.h>
#include "apierror.h"

typedef enum AR_TAGS 
{
	AR_TAG_BADTAG = 0,
	AR_TAG_IPADDR,
	AR_TAG_PORTNUM,
	AR_TAG_APPGUID,
	AR_TAG_USERNAME,
	AR_TAG_NAPPS,
	AR_TAG_QUERYURL,
	AR_TAG_USERID,
	AR_NUM_TAGS
} ARTag;

typedef enum AR_CONFIGTAGS
{
	AR_CONFIG_BADTAG = 0,
	AR_CONFIG_PROXY,
	AR_CONFIG_PROXYPORT,
	AR_CONFIG_SERVERURL,
	AR_NUM_CONFIGTAGS
} ARConfigTag;

//This is the base of the server errors, 
//All HTTP return codes are added to this
//base error to create the actual return
//value.
#define ERROR_SERVER_ERROR_BASE (ERROR_LOCAL_BASE_ID + 0x200)

#define AR_OLE_FAIL(x) ((HRESULT)MAKE_HRESULT(SEVERITY_ERROR, \
											  FACILITY_ARSCLIENT, (x)))

#define AR_OLE_SUCCESS(x) ((HRESULT)MAKE_HRESULT(SEVERITY_SUCCESS, \
										   FACILITY_ARSCLIENT, (x)))

#define AR_OK					AR_OLE_SUCCESS(ERROR_SUCCESS)
#define AR_WINSOCK_STARTUP		AR_OLE_FAIL(ERROR_DLL_INIT_FAILED)
#define AR_WINSOCK_VERSION		AR_OLE_FAIL(ERROR_OLD_WIN_VERSION)
#define AR_ADDRLEN				AR_OLE_FAIL(ERROR_BAD_LENGTH)
#define AR_STRING_INVALID		AR_OLE_FAIL(ERROR_INTERNAL_ERROR)
#define AR_SOCKERROR			AR_OLE_FAIL(ERROR_WRITE_FAULT)
#define AR_INVALID_RESPONSE		AR_OLE_FAIL(ERROR_INVALID_DATA)
#define AR_SERVER_ERROR			AR_OLE_FAIL(ERROR_SERVER_ERROR_BASE)
#define AR_PEER_UNREACHABLE		AR_OLE_FAIL(ERROR_HOST_UNREACHABLE)
#define AR_OUTOFMEMORY			AR_OLE_FAIL(ERROR_OUTOFMEMORY)
#define AR_INVALID_PARAMETER	AR_OLE_FAIL(ERROR_INVALID_PARAMETER)
#define AR_NOT_IMPLEMENTED		AR_OLE_FAIL(ERROR_INVALID_FUNCTION)
#define AR_BAD_TARGET			AR_OLE_FAIL(ERROR_OPEN_FAILED)
#define	AR_BADCONTEXT			AR_OLE_FAIL(ERROR_INVALID_ADDRESS)

//
// Local data types
//

typedef void* ARRegContext;
typedef void* ARCallTargetInfoContext;
typedef char* ARString;

//
//	Function prototypes
//

#ifdef __cplusplus
extern "C" {				// Assume C declarations for C++.
#endif // __cplusplus

/*----------------------------------------------------------------------------
 * ARCreateRegistration
 * DLL entry point
 * 
 * Takes server information and registers with that server, creating
 * a context which must be used to unregister.
 *
 * Returns error code indicating success or failure.
 *
 * Parameters:
 *
 *      regContext  Pointer to a registration
 *                    context to be filled (ARRegContext)
 *      appGUID     GUID of application to register
 *      appName     Displayable name of application to register
 *		appMIME		MIME type for the application
 *      port        The application port to register
 *      ipAddress   IP address to register
 *                    if NULL, will be gathered from registry
 *      userGUID    GUID of user to register
 *                    if NULL, will be gathered from registry
 *      userName    Displayable name of user to register
 *                    if NULL, will be gathered from registry
 *      flags       ULS-compatible flags
 *      ttl         Time to live (time between keep-alives)
 *
 * Returns:
 *      AR_OK					Success
 *		AR_INVALID_PARAMETER	
 *		AR_NOT_IMPLEMENTED		This call has not been implemented.
 *		AR_OUTOFMEMORY			Could not allocate memory for context 
 *		AR_WINSOCK_STARTUP		Error initializing WinSock 
 *		AR_WINSOCK_VERSION		Invalid WinSock version
 *		AR_STRING_INVALID		Could not parse URL to find address and port 
 *		AR_PEER_UNREACHABLE		Could not open TCP socket to server 
 *		AR_SOCKERROR			Could not send request over socket 
 *		AR_INVALID_RESPONSE		Server's response was not of the proper form 
 *		AR_SERVER_ERROR			Server returned an error code
 *		AR_ADDRLEN				The IP address exceeds the maximum length
 *-------------------------------------------------------------------------*/
HRESULT DllExport 
ARCreateRegistration( const char    *appID, 		// IN
                      const char    *appName, 		// IN
  					  const char    *appMIME,		// IN
                      const LONG     port, 			// IN
                      const char    *ipAddress, 	// IN
                      const char    *userID, 		// IN
                      const char    *userName, 		// IN
                      const LONG     flags, 		// IN
                      const LONG     ttl, 			// IN
					  ARRegContext  *regContext);	// OUT

/*---------------------------------------------------------------------------
 * ARDestroyRegistration
 * DLL entry point
 *
 * Removes the registration associated with the given context and
 * destroys the context.
 *
 * Returns error code indicating success or failure.
 *
 * Parameters:
 *
 *      regContext  Pointer to the ARRegContext to destroy
 *
 * Returns:
 *      AR_OK					Success
 *		AR_INVALID_PARAMETER	regContext == NULL
 *		AR_NOT_IMPLEMENTED		This call has not been implemented.
 *		AR_OUTOFMEMORY			Could not allocate memory for context 
 *		AR_WINSOCK_STARTUP		Error initializing WinSock 
 *		AR_WINSOCK_VERSION		Invalid WinSock version
 *		AR_STRING_INVALID		Could not parse URL to find address and port 
 *		AR_PEER_UNREACHABLE		Could not open TCP socket to server 
 *		AR_SOCKERROR			Could not send request over socket 
 *		AR_INVALID_RESPONSE		Server's response was not of the proper form 
 *		AR_SERVER_ERROR			Server returned an error code
 *		AR_ADDRLEN				The IP address exceeds the maximum length
 *-------------------------------------------------------------------------*/
HRESULT DllExport ARDestroyRegistration(ARRegContext regContext); 	// IN

/*-------------------------------------------------------------------------
 * ARCreateCallTargetInfo
 * DLL entry point
 *
 * Given a string, creates a context object which can be used to
 * query fields within a call target delivered by that string
 * NOTE: The intention is that a command line be passed, which
 * can then be interpreted freely by the DLL in an application-
 * independent manner to indicate the call target.
 *
 * Returns error code indicating success or failure.
 *
 * Parameters:
 *
 *      rawTarget   String to be used to derive call target information
 *      ctiContext  Pointer to a call target information context
 *                  to be filled
 *
 * Returns:
 *      AR_OK					Success
 *		AR_INVALID_PARAMETER	(ctiContext || rawTarget) == NULL
 *		AR_BAD_TARGET			We could not create the call target info with
 *								the raw target passed in.
 *		AR_NOT_IMPLEMENTED		This call has not been implemented.
 *-------------------------------------------------------------------------*/
HRESULT DllExport 
ARCreateCallTargetInfo(const char*	rawTarget, 					// IN
                       ARCallTargetInfoContext*	ctiContext);	// OUT

/*---------------------------------------------------------------------------
 * ARQueryCallTargetInfo
 * DLL entry point
 *
 * Given a call target information context, will return the value of a
 * given tag.  Tag names are case insensitive.
 *
 * Returns error code indicating success or failure.
 *
 * Parameters:
 *
 *      ctiContext  A call target information context to query
 *      tagField    A tag to get the value for.
 *
 *		  Valid tags:
 *
 *				AR_TAG_BADTAG = 0	(Place keep for illegal tag value)
 *				AR_TAG_IPADDR
 *				AR_TAG_PORTNUM
 *				AR_TAG_APPGUID
 *				AR_TAG_USERNAME
 *				AR_TAG_NAPPS
 *				AR_TAG_QUERYURL
 *
 *      value       Pointer to location to store value.
 *                    Stored as a null-terminated string.
 *
 * Returns:
 *      AR_OK					Success
 *		AR_INVALID_PARAMETER	(ctiContext || value) == NULL
 *								tagField == AR_TAG_BADTAG
 *		AR_INVALID_RESPONSE		The call target information is invalid
 *								for the specified tag.
 *		AR_NOT_IMPLEMENTED		This call has not been implemented.
 *-------------------------------------------------------------------------*/
HRESULT DllExport 
ARQueryCallTargetInfo(ARCallTargetInfoContext	ctiContext, // IN
 					  ARTag						tagField, 	// IN
                      ARString*            		value); 	// OUT

/*---------------------------------------------------------------------------
 * ARDestroyCallTargetInfo
 * DLL entry point
 *
 * Destroys a call target information context
 *
 * Returns error code indicating success or failure.
 *
 * Parameters:
 *
 *      ctiContext  The call target information context to destroy
 *
 * Returns:
 *      AR_OK					Success
 *		AR_INVALID_PARAMETER	ctiContext == NULL
 *		AR_NOT_IMPLEMENTED		This call has not been implemented.
 *-------------------------------------------------------------------------*/
HRESULT DllExport 
ARDestroyCallTargetInfo(ARCallTargetInfoContext ctiContext); 	// IN


/*---------------------------------------------------------------------------
 * ARGetConfigVal
 * DLL entry point
 *
 * Obtain specified ARS configuration value
 *
 * Returns error code indicating success or failure.
 *
 * Parameters:
 *
 *      tagField    A tag to get the value for.
 *
 *		  Valid tags:
 *
 *				AR_CONFIG_BADTAG = 0	(Place keep for illegal tag value)
 *				AR_CONFIG_PROXY
 *				AR_CONFIG_PROXYPORT
 *				AR_CONFIG_SERVERURL
 *
 *      value       Pointer to location to store pointer to value.
 *                    Stored as a null-terminated string;
 *						allocated by DLL
 *
 * Returns:
 *      AR_OK					Success
 *		AR_INVALID_PARAMETER	tagField == AR_TAG_BADTAG
 *		AR_BAD_TARGET			Could not open registry for reading
 *		AR_NOT_IMPLEMENTED		This call has not been implemented.
 *-------------------------------------------------------------------------*/
HRESULT DllExport 
ARGetConfigVal(	ARConfigTag					tagField,	// IN
				ARString*              		value);		// OUT

/*---------------------------------------------------------------------------
 * ARSetConfigVal
 * DLL entry point
 *
 * Set specified ARS configuration value
 *
 * Returns error code indicating success or failure.
 *
 * Parameters:
 *
 *      tagField    A tag to get the value for.
 *					Valid tags are those valid for ARGetConfigVal
 *      value       Pointer to location to store pointer to value.
 *                    Stored as a null-terminated string;
 *						allocated by DLL
 *
 * Returns:
 *      AR_OK					Success
 *		AR_INVALID_PARAMETER	tagField == AR_TAG_BADTAG
 *		AR_BAD_TARGET			Could not open registry for writing
 *		AR_NOT_IMPLEMENTED		This call has not been implemented.
 *-------------------------------------------------------------------------*/
HRESULT DllExport 
ARSetConfigVal(	ARConfigTag					tagField,	// IN
				const char					*value);	// IN


/*---------------------------------------------------------------------------
 * ARReleaseStringResult
 * DLL entry point
 *
 * Destroys a string allocated by ARGetConfigVal or ARQueryCallTargetInfo
 *
 * Returns error code indicating success or failure.
 *
 * Parameters:
 *
 *      value  The string to destroy
 *
 * Returns:
 *      AR_OK					Success
 *		AR_INVALID_PARAMETER	value == NULL
 *-------------------------------------------------------------------------*/
HRESULT DllExport ARReleaseStringResult(ARString value);	// IN

/*---------------------------------------------------------------------------
 * ARGetHostByAddr
 * DLL entry point
 *
 * Converts IP addr in dot notation to a host name.
 *
 * Returns error code indicating success or failure.
 *
 * Parameters:
 *
 *      lpszAddr	ptr to string containing IP addr in dot notation
 *		pphostName	address of ptr to store the host name
 *
 * Returns:
 *      AR_OK					Success
 *		AR_INVALID_PARAMETER	value == NULL
 *-------------------------------------------------------------------------*/

HRESULT DllExport ARGetHostByAddr(const char* lpszAddr,		// IN
								  char** pphostName);		// OUT

#ifdef __cplusplus
}						// End of extern "C" {
#endif // __cplusplus

/****************************************************************************
 *
 * $Log:   S:\sturgeon\src\include\vcs\arscli.h_v  $
 * 
 *    Rev 1.6   23 Sep 1996 08:45:14   ENBUSHX
 * No change.
 * 
 *    Rev 1.5   19 Sep 1996 19:29:52   ENBUSHX
 * Fubction to translate from IP DOT to domain name.
 * 
 *    Rev 1.4   19 Sep 1996 18:58:34   ENBUSHX
 * Added a define for user id field in iii file.
 * 
 *    Rev 1.3   11 Jul 1996 18:42:12   rodellx
 * 
 * Fixed bug where HRESULT ids were in violation of Facility and/or Code
 * value rules.
 * 
 *    Rev 1.2   10 Jul 1996 18:40:52   rodellx
 * 
 * Moved definition of arscli facility to apierror.h.
 * 
 *    Rev 1.1   08 Jul 1996 14:50:48   GEHOFFMA
 * Don't think any changes were made... just to be sure
 *
 ***************************************************************************/

#endif // ARSCLIENT_H