/////////////////////////////////////////////////////////////////////////////
//
//  Knight OPC Client Rapid Development Toolkits For Multi Servers
//								(Header File)
//
/////////////////////////////////////////////////////////////////////////////
//
//          Author: Knight Fox
//    Initial Date: 11/18/2001
//       $Workfile: KOCRDKApi.h $
//       $Revision: 2.0 $
//           $Date: Oct/18/2002 2:15p $
//   Target System: Microsoft Windows NT 4.0 / 95 /98 / 2000 / XP
//     Environment: Visual C++ 6.0 / OPC DataAccess 2.0
//         Remarks: Multi Server Version
//  Product Update: http://www.eehoo.net
//         Contact: opc@eehoo.net
//
/////////////////////////////////////////////////////////////////////////////
//  Copyright (C) 2002, Knight Workgroup, eehoo Technologies, Inc. 
/////////////////////////////////////////////////////////////////////////////


#if !defined(KOCRDK_H)
#define KOCRDK_H

#ifdef STRICT
typedef VOID (CALLBACK* DATACHANGEPROC)(HANDLE, HANDLE, HANDLE, VARIANT*, FILETIME, DWORD);
typedef VOID (CALLBACK* SHUTDOWNPROC)(HANDLE);
#else /* !STRICT */
typedef FARPROC DATACHANGEPROC;
typedef FARPROC SHUTDOWNPROC;
#endif



#ifdef __cplusplus
extern "C" {
#endif  /* __cplusplus */


// The following ifdef block is the standard way of creating macros which make exporting 
// from a DLL simpler. All files within this DLL are compiled with the KOCRDK_EXPORTS
// symbol defined on the command line. this symbol should not be defined on any project
// that uses this DLL. This way any other project whose source files include this file see 
// KOCRDK_API functions as being imported from a DLL, wheras this DLL sees symbols
// defined with this macro as being exported.
#ifdef KOCRDK_EXPORTS
#define KOCRDK_API __declspec(dllexport)
#else
#define KOCRDK_API __declspec(dllimport)
#endif

/*******************************************************************************************/
/******************** API Function List  ************************************************/
/*******************************************************************************************/

///////////////////////////////////////////////////////////////////////////////////////////
//
// CallBack Functions
//
//////////////////////////////////////////////////////////////////////////////////////////

/////////////////////////////////////
// KOC_SetDataChangeProc
//
// Establishes a callback function in the user application which will receive
// control when the value of an item is updated from the connected server.
//
// prototype for the callback function is as follows:
//		void CALLBACK EXPORT DataChangeProc(HANDLE hGroup, HANDLE hItem, VARIANT *pVar, FILETIME timestamp, DWORD quality)
//
//	Param:	HANDLE hConnect				--	HANDLE of connected opc server
//			DATACHANGEPROC lpCallback	--	pointer of callback function  in user application
//	Return:	BOOL						--	TRUE if succeded, FALSE if failed
KOCRDK_API BOOL  WINAPI KOC_SetDataChangeProc(HANDLE hConnect, DATACHANGEPROC lpCallback);

//
// KOC_SetShutdownProc
//
// Establishes a callback to the application if the connected
// server requests a disconnect;
//
//	Param:	HANDLE hConnect				--	HANDLE of connected opc server
//			SHUTDOWNPROC lpCallback		--	pointer of callback function  in user application
//	Return:	BOOL						--	TRUE if succeded, FALSE if failed
KOCRDK_API BOOL  WINAPI KOC_SetShutdownProc(HANDLE hConnect, SHUTDOWNPROC lpCallback);



///////////////////////////////////////////////////////////////////////////////////////////
//
// Initialization and System functions
//
///////////////////////////////////////////////////////////////////////////////////////////
//
// KOC_GetVersion()
//
// This function simply returns a DWORD version info
//
KOCRDK_API DWORD WINAPI KOC_GetVersion();

//
// KOC_Init()
//
// This function initializes KOCRDK.dll
//
KOCRDK_API BOOL WINAPI KOC_Init();

//
// KOC_Uninit()
//
// This function uninitializes KOCRDK.dll 
//
KOCRDK_API void WINAPI KOC_Uninit();


///////////////////////////////////////////////////////////////////////////////////////////
//
// OPC Server functions
//
///////////////////////////////////////////////////////////////////////////////////////////

//
// KOC_GetServerCount
//
// returns the number of available local or remote OPC servers 
//
// Param: BOOL bVer2			--	TRUE , find OPC 2.0 servers
//								--	FALSE, find OPC 1.0 servers
//
KOCRDK_API int WINAPI KOC_GetServerCount(LPCSTR MachineName,BOOL bVer2 = true);

//
// KOC_GetServerName
//
// Used to iterate through the server list obtained with KOC_GetServerCount()
// User Buffer pointed to by pBuf is filled with the Server name at index of the Server List
// A returned value of FALSE indicates that the index is invalid.
//
KOCRDK_API BOOL  WINAPI KOC_GetServerName(int index, char *pBuf, int BufSize);

//
// KOC_Connect 
//
// Establishes an OPC Connection with the specified server
// INVALID_HANDLE_VALUE (-1) id returned if the connection cannot be established.
//
// Param: BOOL bVer2			--	TRUE , using OPC 2.0 interface
//								--	FALSE, using OPC 1.0 interface
//
KOCRDK_API HANDLE  WINAPI KOC_Connect(LPCSTR MachineName, LPCSTR ServerName, BOOL bVer2 = true);

//
// KOC_Disconnect
//
// Used to shutdown an OPC Connection
//
KOCRDK_API void  WINAPI KOC_Disconnect(HANDLE hConnect);

//
// GetSvrStatus (...)
// 
// Allows the controlling application to get the running
// status of an attached server.  
//
KOCRDK_API BOOL WINAPI KOC_GetServerStatus(HANDLE hConnect, OPCSERVERSTATUS **pSvrStatus);


///////////////////////////////////////////////////////////////////////////////////////////
//
// OPC Group functions
//
///////////////////////////////////////////////////////////////////////////////////////////
//
// KOC_AddGroup
//
// Creates a new OPC Group for the defined connection
// Requested name, data rate and deadband etc. specified in parameter list.
// 
KOCRDK_API HANDLE  WINAPI KOC_AddGroup (
								HANDLE	hConnect, 
								LPCSTR	Name, 
								BOOL	*bActive, 
								DWORD	*pRate, 
								LONG	*pTimeBias,
								float	*pDeadBand,
								DWORD	*dwLCID);

//
// KOC_RemoveGroup
//
// Removes and cleansup allocated resources for defined group
//
KOCRDK_API void  WINAPI KOC_RemoveGroup(HANDLE hConnect, HANDLE hGroup);

KOCRDK_API BOOL  WINAPI KOC_SetGroupName(HANDLE hConnect, HANDLE hGroup, LPCSTR Name);

KOCRDK_API BOOL  WINAPI KOC_SetGroupStat(
								HANDLE	hConnect, 
								HANDLE	hGroup, 
								DWORD	*pRate, 
								BOOL	*bActive,
								LONG	*pTimeBias,
								float	*pDeadBand, 
								DWORD	*dwLCID);

KOCRDK_API BOOL  WINAPI KOC_GetGroupStat(
								HANDLE	hConnect, 
								HANDLE	hGroup, 
								LPCSTR	Name,
								DWORD	*pRate, 
								BOOL	*bActive,
								LONG	*pTimeBias,
								float	*pDeadBand, 
								DWORD	*dwLCID);


///////////////////////////////////////////////////////////////////////////////////////////
//
// OPC Item functions
//
///////////////////////////////////////////////////////////////////////////////////////////

//
// KOC_GetItemCount
//
// Returns the number of OPC Items from the Browse Interface of the designated
// Server connection.  If the server does not support Browsing, a value of xero
// is returned.  This function fills an internal array of itemnames which may
// then be accessed via KOC_GetItemName().
//
// This function is equivalent to calling BrowseItems using OPC_FLAT from
// the Root position.
//
KOCRDK_API int  WINAPI KOC_GetItemCount(HANDLE hConnect);

//
// KOC_GetItemName
//
// Allows user to iterate through the list of item names obtained from
// KOC_GetItemCount().
//
KOCRDK_API BOOL  WINAPI KOC_GetItemName(HANDLE hConnect, int index, char *pBuf, int BufSize);

//
// KOC_AddItem
//
// Requests that the connected OPC Server add an item to the specified group.
// The return value identifies the item for future access by the user application.
// An INVALID_HANDLE_VALUE return, indicates that the requested item name does not
// exist in the connected Server.
//
KOCRDK_API HANDLE  WINAPI KOC_AddItem(HANDLE hConnect, HANDLE hGroup, LPCSTR ItemName);

//
// KOC_RemoveItem
//
// Removes the specified OPC Item and cleans up resources
//
KOCRDK_API void  WINAPI KOC_RemoveItem(HANDLE hConnect, HANDLE hGroup, HANDLE hItem);


//
// KOC_WriteItem
//
// Allows the controlling application to write to a defined OPC item
//
//
KOCRDK_API BOOL  WINAPI KOC_WriteItem(HANDLE hConnect, HANDLE hGroup, HANDLE hItem, VARIANT *pVar, BOOL DoAsync);


//
// KOC_ReadItem
//
// Uses the SyncIO Interface to read an opc item directly from the Server.
//
KOCRDK_API BOOL  WINAPI KOC_ReadItem(HANDLE hConnect, HANDLE hGroup, HANDLE hItem, VARIANT *pVar, FILETIME *pTimeStamp, DWORD *pQuality);

//
// KOC_ActiveItem
//
// Active or Inactive a OPC item .
//
//	Return:	BOOL						--	TRUE if succeded, FALSE if failed
KOCRDK_API BOOL  WINAPI KOC_ActiveItem(HANDLE hConnect, HANDLE hGroup, HANDLE hItem, BOOL bActive);

//
// KOC_ValidateItem
//
// Allows the application to obtain the canonical data type and
// read/write access properties for a given item.
//
KOCRDK_API BOOL  WINAPI KOC_ValidateItem(HANDLE hConnect, HANDLE hGroup, LPCSTR Name, VARTYPE *pType, DWORD *pAccessRights);


/////////////////////////////////////////////////////////////////////////////////////
//
// Browse functions
//
/////////////////////////////////////////////////////////////////////////////////////
//
// KOC_SetBrowseFilters
//
// Allows the application to specify filters to use during Browse Operations.
// Item names may be filtered based on user defined string, data type, or
// Read/Write access rights
//
KOCRDK_API BOOL  WINAPI KOC_SetBrowseFilters (HANDLE hConnect, LPCSTR FilterString, VARTYPE DataType, DWORD AccessType);

//
// KOC_GetNameSpace
//
// returns OPC_NS_FLAT (2) or OPC_NS_HIERARCHIAL (1) for the specified server connection
//
KOCRDK_API BOOL  WINAPI KOC_GetNameSpace (HANDLE hConnect, WORD *pNameSpace);

//
// KOC_BrowseToNode
//
// Changes the current browse position for the server to the specified node.
// Use a NULL String  to browse to the top of the tree.
//
KOCRDK_API BOOL  WINAPI KOC_BrowseToNode (HANDLE hConnect, LPCSTR NodeName);


//
// KOC_BrowseItems
//
// Returns the number of items from the current browse position and fills
// the internal item name array with the node names that may be accessible 
// via GetItemName().
//
// The Filter parameter specifies:
//	OPC_BRANCH: returns only items that have children
//	OPC_LEAF: returns only items that don't have children
//	OPC_FLAT: Returns all OPC Item Names, (LEAFS ONLY), below the current position
//				(including all children of children).
// 
KOCRDK_API int  WINAPI KOC_BrowseItems (HANDLE hConnect, WORD FilterType);

// KOC_GetItemFullName
//
// Returns the fully qualified item name from the server.
// uses the OPCBrowseAddressSpace::GetItemID Interface.
//
// 
KOCRDK_API BOOL  WINAPI KOC_GetItemFullName (HANDLE hConnect, LPCSTR ItemName, char *pQualifiedName, int BufSize);



//
// KOC_NumberOfItemProperties
//
// Returns the number of item Properties for the specified item.
//
KOCRDK_API int  WINAPI KOC_NumberOfItemProperties (HANDLE hConnect, LPCSTR ItemName);

//
// KOC_GetItemPropertyDescription
//
// Returns the property values description for the last item specified 
// by KOC_NumberOfItemProperties().  The application may use the returned PropertyID
// to read the property value from the server using KOC_ReadPropertyValue().
//
KOCRDK_API BOOL  WINAPI KOC_GetItemPropertyDescription (HANDLE hConnect, int PropertyIndex, DWORD *pPropertyID, VARTYPE *pVT, CHAR *pDesc);//BYTE *pDescr, int BufSize);
 
//
// KOC_ReadPropertyValue
//
// Returns the property value for the item specified 
//
KOCRDK_API BOOL  WINAPI KOC_ReadPropertyValue (HANDLE hConnect, LPCSTR Itemname, DWORD PropertyID, VARIANT *pValue);



/////////////////////////////////////////////////////////////////////////////////////////////
//
//  Product Registration Functions
//
////////////////////////////////////////////////////////////////////////////////////////////
KOCRDK_API void WINAPI KOC_Active(LPCSTR Name, LPCSTR Code);	        


/*******************************************************************************************/
/******************** API Function List End Here *******************************************/
/*******************************************************************************************/



#ifdef __cplusplus
}
#endif

#endif