/*++
*****************************************************************************
* Copyright (c) 1997 Digi International Inc., All Rights Reserved
* 
* This software contains proprietary and confidential information of Digi
* International Inc.  By accepting transfer of this copy, Recipient agrees
* to retain this software in confidence, to prevent disclosure to others,
* and to make no use of this software other than that for which it was
* delivered.  This is an unpublished copyrighted work of Digi International
* Inc.  Except as permitted by federal law, 17 USC 117, copying is strictly
* prohibited.
* 
* Restricted Rights Legend
*
* Use, duplication, or disclosure by the Government is subject to
* restrictions set forth in sub-paragraph (c)(1)(ii) of The Rights in
* Technical Data and Computer Software clause at DFARS 252.227-7031 or
* subparagraphs (c)(1) and (2) of the Commercial Computer Software -
* Restricted Rights at 48 CFR 52.227-19, as applicable.
*
* Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
*
*****************************************************************************

File: DxbShim.h

--*/

#ifndef DxbShim_h
#define DxbShim_h

#if !defined (API_DECL)
#define API_DECL __declspec( dllimport ) WINAPI
#endif /* #if !defined (API_DECL) */

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

typedef enum SHIM_STATUS
{
	SHIM_STATUS_SUCCESS,				/* No Error */
	SHIM_STATUS_NONE,					/* No status available, use for default */
	SHIM_STATUS_PENDING_OPERATION,/* Operation is pending, event will be signaled when complete */
	SHIM_ERROR_GENERAL,				/* Operation failed, no further information */
	SHIM_ERROR_DRIVER_OPEN,			/* CreateFile() failed on a driver or device */
	SHIM_ERROR_DRIVER_CLOSE,		/* CloseHandle() failed on a driver or device */
	SHIM_ERROR_CREATE_EVENT,		/* CreateEvent() failed */
	SHIM_ERROR_IO_NOT_PENDING,		/* Expected DeviceIoControl() ERROR_IO_PENDING */
	SHIM_ERROR_IO_RESULT_COUNT,	/* IOCTL operation result had wrong byte count */
	SHIM_ERROR_GET_OL_RESULT,		/* GetOverlappedResult() failed */
	SHIM_ERROR_OL_RESULT_COUNT,	/* Overlapped operation result had wrong byte count */
	SHIM_ERROR_EVENT_CLOSE,			/* CloseHandle() failed closing event */
	SHIM_ERROR_MEMORY_ALLOC,		/* malloc() failed */
	SHIM_ERROR_INVALID_DS_IOCTL,	/* value for IOCTL_DS_X was invalid */
	SHIM_ERROR_INVALID_OP_TYPE,	/* Invalid operation type for IOCTL */
	SHIM_ERROR_OPERATION_TIMEOUT,	/* The time-out expired, operation cancelled */
	SHIM_ERROR_CANCEL_IO,			/* Failure cancelling I/O request */
	SHIM_ERROR_THREAD_START,		/* Thread failed to start */
	SHIM_ERROR_STRING_ERROR,		/* String wasn't NULL terminated or too big */
	SHIM_ERROR_STREAM_OPEN,			/* Stream open returned non-zero error code */
	SHIM_ERROR_NOT_INITIALIZED,	/* Required init was not performed */
	SHIM_ERROR_EXPECTED_SIZE,		/* Operation returned with incorrect data size */
	SHIM_ERROR_DS_IOCTL_INTERNAL,	/* DS_IOCTL operation return value or error code was non-zero */
	SHIM_ERROR_DS_LINK_INTERNAL,	/* DS_LINK operation error code was non-zero */
	SHIM_ERROR_DS_OPEN_INTERNAL,	/* DS_OPEN operation error code was non-zero */
	SHIM_ERROR_USER_CANCEL,			/* User canceled an async operation */
	SHIM_ERROR_SHUTDOWN,				/* User canceled an async operation */
	SHIM_ERROR_INVALID_PARAMETER,	/* Input parameter was incorrect */
	SHIM_ERROR_INVALID_HANDLE,		/* Handle was NULL */
	SHIM_ERROR_TIME_TO_BAIL,		/* Application is shutting down, terminate immediately */
	SHIM_ERROR_LAST_ENTRY
}SHIM_STATUS;

#define MAX_DOS_DEVICE_NAME 64

/*
 * Global Operations
 */

void API_DECL
DxbShutdown(void);

/*
 * Device Operations
 */

SHIM_STATUS API_DECL
DxbDeviceOpen(	IN TCHAR const * const pszDeviceName,
					OUT HANDLE * const phDevice
					);

SHIM_STATUS API_DECL
DxbDeviceClose(IN HANDLE const hDevice);

/*
 * Wrapped Device IOCTLs which facilitate streams operations
 *
 * 4 modes are available:
 * Blocking			- (0 == TimoutMs) && (NULL == hEvent)
 *		Call blocks until the operation completes
 *
 * Async				- (0 == TimoutMs) && (NULL != hEvent)
 *		Call returns immediately, hEvent is signaled upon completion
 *
 * Time-out			- (0 != TimoutMs) && (NULL == hEvent)
 *		Call blocks for specified time-out, cancelled if time-out expires
 *
 * Async Time-out	- (0 != TimoutMs) && (NULL != hEvent)
 *		Call returns immediately, hEvent signaled when operation completes
 *		or time-out expires, cancelled if expired
 *	
 * Note that Time-out is only available for NT4.0 and above
 *
 */

SHIM_STATUS API_DECL
DxbStreamOpen(	IN HANDLE const hDevice,
					IN TCHAR const * const pszStreamName,
					OUT HANDLE * const phStream,
					OUT LONG * const pErrorCode,
					IN DWORD const TimeoutMs,
					IN HANDLE const hEvent,
					OUT SHIM_STATUS * const pStatus
					);

SHIM_STATUS API_DECL
DxbStreamClose(IN HANDLE const hDevice,
					IN HANDLE const hStream,
					IN DWORD const TimeoutMs,
					IN HANDLE const hEvent,
					OUT SHIM_STATUS * const pStatus
					);

SHIM_STATUS API_DECL
DxbStreamIoctl(IN HANDLE const hDevice,
					IN HANDLE const hStream,
					IN ULONG const Command,
					IN LONG const Timeout,
					IN OUT VOID * const pDataIn,
					IN ULONG const cbDataIn,
					OUT VOID * const pDataOut,
					IN ULONG const cbMaxDataOut,
					OUT ULONG * const pcbDataOut,
					OUT LONG * const pReturnValue,
					OUT LONG * const pErrorCode,
					IN DWORD const TimeoutMs,
					IN HANDLE const hEvent,
					OUT SHIM_STATUS * const pStatus
					);

SHIM_STATUS API_DECL
DxbStreamLink(	IN HANDLE const hDevice,
					IN HANDLE const hStreamUpper,
					IN HANDLE const hStreamLower,
					OUT LONG * const pMuxId,
					OUT LONG * const pErrorCode,
					IN DWORD const TimeoutMs,
					IN HANDLE const hEvent,
					OUT SHIM_STATUS * const pStatus
					);

/* Priority */
typedef enum MSG_PRIORITY_VALUES
{
	MSG_PRIORITY_LOW,
	MSG_PRIORITY_HIGH
}MSG_PRIORITY_T;

SHIM_STATUS API_DECL
DxbStreamPutMsg(	IN HANDLE const hDevice,
						IN HANDLE const hStream,
						IN void const * const pControlBuffer,
						IN ULONG const ControlLength,
						IN void const * const pDataBuffer,
						IN ULONG const DataLength,
						IN MSG_PRIORITY_T const Priority,
						IN DWORD const TimeoutMs,
						IN HANDLE const hEvent,
						OUT SHIM_STATUS * const pStatus
						);

SHIM_STATUS API_DECL
DxbStreamGetMsg(	IN HANDLE const hDevice,
						IN HANDLE const hStream,
						IN OUT void * const  pControlBuffer,
						IN ULONG const ControlMaxLength,
						OUT ULONG * const	pControlLength,
						IN OUT void * const pDataBuffer,
						IN ULONG const DataMaxLength,
						OUT ULONG * const pDataLength,
						IN MSG_PRIORITY_T const Priority,
						IN DWORD const TimeoutMs,
						IN HANDLE const hEvent,
						OUT SHIM_STATUS * const pStatus
						);

/* Flags values - bitfields */
#define	PURGE_WRITE	 0x00000001
#define	PURGE_READ	 0x00000002
#define	PURGE_PUTMSG 0x00000004
#define	PURGE_GETMSG 0x00000008
#define	PURGE_ALL	 (PURGE_WRITE|PURGE_READ|PURGE_PUTMSG|PURGE_GETMSG)

SHIM_STATUS API_DECL
DxbStreamPurge(IN HANDLE const hDevice,
					IN HANDLE const hStream,
					IN ULONG  const Flags,
					IN DWORD const TimeoutMs,
					IN HANDLE const hEvent,
					OUT SHIM_STATUS * const pStatus
					);

SHIM_STATUS API_DECL
CancelAsyncOperation(HANDLE hAsyncOperation);

/* MemoryFlag values */
/* mutually exclusive */
typedef enum KME_MEMORY_FLAG_VALUES
{
	KME_MEMORY_FLAG_ADAPTER_MEMORY,
	KME_MEMORY_FLAG_HOST_MEMORY,
	KME_MEMORY_FLAG_PCI_INTERFACE_CHIP,
	KME_MEMORY_FLAG_PCI_MEMORY_OTHER,
	KME_MEMORY_FLAG_LAST_ENTRY
} KME_MEMORY_FLAG_T;

SHIM_STATUS API_DECL
DxbKmeWrite(	IN HANDLE const hDevice,
					IN DWORD const Address,
					IN KME_MEMORY_FLAG_T const MemoryFlag,
					IN void * const pBuffer,
					IN DWORD const cbBuffer,
					OUT DWORD * const pcbWritten,
					IN DWORD const TimeoutMs,
					IN HANDLE const hEvent,
					OUT SHIM_STATUS * const pStatus
				);

SHIM_STATUS API_DECL
DxbKmeRead(	IN HANDLE const hDevice,
				IN DWORD const Address,
				IN KME_MEMORY_FLAG_T const MemoryFlag,
				OUT void * pBuffer,
				IN DWORD const cbBufferMax,
				OUT DWORD * const pcbBuffer,
				IN DWORD const TimeoutMs,
				IN HANDLE const hEvent,
				OUT SHIM_STATUS * const pStatus
			);

#if defined(__cplusplus)
}
#endif

#endif /* #ifndef DxbShim_h */
