// 這是CH372和CH375的Windows98/ME/2000/XP簡化版驅動程序, 僅供學習USB驅動開發
// 稍加修改完全可以用于其它USB芯片, 不過作者希望你是用于CH372和CH375芯片
// 2003.09.08, 2003.12.28, 2004.10.15, 2004.12.05, 2004.12.10, 2005.01.20, 2005.02.23, 2005.07.15
//****************************************
//**  Copyright  (C)  W.ch  1999-2005   **
//**  Web:  http://www.winchiphead.com  **
//****************************************
//**  DLL for USB interface chip CH375  **
//**  C, VC5.0                          **
//****************************************
//
// USB總線接口芯片CH375的應用層接口庫  V0.1
// 南京沁恒電子有限公司  作者: W.ch 2005.07
// CH375-DLL  V0.1 , Support: Ctrl/Bulk/Int
// 運行環境: Windows 98/ME, Windows 2000/XP
// support USB chip: CH372/CH375
//

#ifndef		_CH375_DLL_H
#define		_CH375_DLL_H

#ifdef __cplusplus
extern "C" {
#endif

#define		mOFFSET( s, m )			( (ULONG) & ( ( ( s * ) 0 ) -> m ) )	// 定義獲取結構成員相對偏移地址的宏

#ifndef		max
#define		max( a, b )				( ( ( a ) > ( b ) ) ? ( a ) : ( b ) )	// 較大值
#endif

#ifndef		min
#define		min( a, b )				( ( ( a ) < ( b ) ) ? ( a ) : ( b ) )	// 較小值
#endif

#ifdef		ExAllocatePool
#undef		ExAllocatePool						// 刪除帶TAG的內存分配
#endif

#ifndef		NTSTATUS
typedef		LONG	NTSTATUS;					// 返回狀態
#endif


typedef	struct	_USB_SETUP_PKT {				// USB控制傳輸的建立階段的數據請求包結構
	UCHAR			mUspReqType;				// 00H 請求類型
	UCHAR			mUspRequest;				// 01H 請求代碼
	union	{
		struct	{
			UCHAR	mUspValueLow;				// 02H 值參數低字節
			UCHAR	mUspValueHigh;				// 03H 值參數高字節
		};
		USHORT		mUspValue;					// 02H-03H 值參數
	};
	union	{
		struct	{
			UCHAR	mUspIndexLow;				// 04H 索引參數低字節
			UCHAR	mUspIndexHigh;				// 05H 索引參數高字節
		};
		USHORT		mUspIndex;					// 04H-05H 索引參數
	};
	USHORT			mLength;					// 06H-07H 數據階段的數據長度
} mUSB_SETUP_PKT, *mPUSB_SETUP_PKT;


#define		mCH375_PACKET_LENGTH	64			// CH375支持的數據包的長度
#define		mCH375_PKT_LEN_SHORT	8			// CH375支持的短數據包的長度


typedef	struct	_WIN32_COMMAND {				// 定義WIN32命令接口結構
	union	{
		ULONG		mFunction;					// 輸入時指定功能代碼或者管道號
		NTSTATUS	mStatus;					// 輸出時返回操作狀態
	};
	ULONG			mLength;					// 存取長度,返回后續數據的長度
	union	{
		mUSB_SETUP_PKT	mSetupPkt;				// USB控制傳輸的建立階段的數據請求
		UCHAR			mBuffer[ mCH375_PACKET_LENGTH ];	// 數據緩沖區,長度為0至255B
	};
} mWIN32_COMMAND, *mPWIN32_COMMAND;


// WIN32應用層接口命令
#define		IOCTL_CH375_COMMAND		( FILE_DEVICE_UNKNOWN << 16 | FILE_ANY_ACCESS << 14 | 0x0f37 << 2 | METHOD_BUFFERED )	// 專用接口

#define		mWIN32_COMMAND_HEAD		mOFFSET( mWIN32_COMMAND, mBuffer )	// WIN32命令接口的頭長度

#define		mMAX_BUFFER_LENGTH		0x0400		// 數據緩沖區最大長度1024

#define		mMAX_COMMAND_LENGTH		( mWIN32_COMMAND_HEAD + mMAX_BUFFER_LENGTH )	// 最大數據長度加上命令結構頭的長度


// 設備層接口提供的管道操作命令
#define		mPipeDeviceCtrl			0x00000004	// CH375的綜合控制管道
#define		mPipeInterUp			0x00000005	// CH375的中斷數據上傳管道
#define		mPipeDataUp				0x00000006	// CH375的數據塊上傳管道
#define		mPipeDataDown			0x00000007	// CH375的數據塊下傳管道
#define		mPipeAuxDown			0x00000008	// CH375的輔助數據下傳管道

// 應用層接口的功能代碼
#define		mFuncGetVersion			0x00000001	// 獲取驅動程序版本號
#define		mFuncResetPipe			0x0000000d	// 復位USB管道
#define		mFuncAbortPipe			0x0000000e	// 取消USB管道的數據請求


typedef		VOID	( CALLBACK	* mPCH375_INT_ROUTINE ) (  // 中斷服務回調程序
	PUCHAR			iBuffer );  // 指向一個緩沖區,提供當前的中斷特征數據


ULONG	WINAPI	CH375GetVersion( );  // 獲得DLL版本號,返回版本號


PVOID	WINAPI	CH375GetDeviceName(  // 返回指向CH375設備名稱的緩沖區,出錯則返回NULL
	ULONG			iIndex );  // 指定CH375設備序號,0對應第一個設備


HANDLE	WINAPI	CH375OpenDevice(  // 打開CH375設備,返回句柄,出錯則無效
	ULONG			iIndex );  // 指定CH375設備序號,0對應第一個設備


VOID	WINAPI	CH375CloseDevice(  // 關閉CH375設備
	ULONG			iIndex );  // 指定CH375設備序號,必須是0


ULONG	WINAPI	CH375DriverCommand(  // 直接傳遞命令給驅動程序,出錯則返回0,否則返回數據長度
	ULONG			iIndex,  // 指定CH375設備序號,必須是0
	mPWIN32_COMMAND	ioCommand );  // 命令結構的指針
// 該程序在調用后返回數據長度,并且仍然返回命令結構,如果是讀操作,則數據返回在命令結構中,
// 返回的數據長度在操作失敗時為0,操作成功時為整個命令結構的長度,例如讀一個字節,則返回mWIN32_COMMAND_HEAD+1,
// 命令結構在調用前,分別提供:管道號或者命令功能代碼,存取數據的長度(可選),數據(可選)
// 命令結構在調用后,分別返回:操作狀態代碼,后續數據的長度(可選),
//   操作狀態代碼是由WINDOWS定義的代碼,可以參考NTSTATUS.H,
//   后續數據的長度是指讀操作返回的數據長度,數據存放在隨后的緩沖區中,對于寫操作一般為0


BOOL	WINAPI	CH375GetDeviceDescr(  // 讀取設備描述符
	ULONG			iIndex,  // 指定CH375設備序號,必須是0
	PVOID			oBuffer,  // 指向一個足夠大的緩沖區,用于保存描述符
	PULONG			ioLength );  // 指向長度單元,輸入時為準備讀取的長度,返回后為實際讀取的長度


BOOL	WINAPI	CH375GetConfigDescr(  // 讀取配置描述符
	ULONG			iIndex,  // 指定CH375設備序號,必須是0
	PVOID			oBuffer,  // 指向一個足夠大的緩沖區,用于保存描述符
	PULONG			ioLength );  // 指向長度單元,輸入時為準備讀取的長度,返回后為實際讀取的長度


BOOL	WINAPI	CH375ReadData(  // 讀取數據塊
	ULONG			iIndex,  // 指定CH375設備序號,必須是0
	PVOID			oBuffer,  // 指向一個足夠大的緩沖區,用于保存讀取的數據
	PULONG			ioLength );  // 指向長度單元,輸入時為準備讀取的長度,返回后為實際讀取的長度


BOOL	WINAPI	CH375AbortRead(  // 放棄數據塊讀操作
	ULONG			iIndex );  // 指定CH375設備序號,必須是0


BOOL	WINAPI	CH375ResetRead(  // 復位數據塊讀操作
	ULONG			iIndex );  // 指定CH375設備序號,必須是0


BOOL	WINAPI	CH375WriteData(  // 寫出數據塊
	ULONG			iIndex,  // 指定CH375設備序號,必須是0
	PVOID			iBuffer,  // 指向一個緩沖區,放置準備寫出的數據
	PULONG			ioLength );  // 指向長度單元,輸入時為準備寫出的長度,返回后為實際寫出的長度


BOOL	WINAPI	CH375AbortWrite(  // 放棄數據塊寫操作
	ULONG			iIndex );  // 指定CH375設備序號,必須是0


BOOL	WINAPI	CH375ResetWrite(  // 復位數據塊寫操作
	ULONG			iIndex );  // 指定CH375設備序號,必須是0


BOOL	WINAPI	CH375ReadInter(  // 讀取中斷數據
	ULONG			iIndex,  // 指定CH375設備序號,必須是0
	PVOID			oBuffer,  // 指向一個足夠大的緩沖區,用于保存讀取的中斷數據
	PULONG			ioLength );  // 指向長度單元,輸入時為準備讀取的長度,返回后為實際讀取的長度


BOOL	WINAPI	CH375AbortInter(  // 放棄中斷數據讀操作
	ULONG			iIndex );  // 指定CH375設備序號,必須是0


BOOL	WINAPI	CH375ResetInter(  // 復位中斷數據讀操作
	ULONG			iIndex );  // 指定CH375設備序號,必須是0


BOOL	WINAPI	CH375SetIntRoutine(  // 設定中斷服務程序
	ULONG			iIndex,  // 指定CH375設備序號,必須是0
	mPCH375_INT_ROUTINE	iIntRoutine );  // 指定中斷服務回調程序,為NULL則取消中斷服務,否則在中斷時調用該程序


BOOL	WINAPI	CH375WriteAuxData(  // 寫出輔助數據
	ULONG			iIndex,  // 指定CH375設備序號,必須是0
	PVOID			iBuffer,  // 指向一個緩沖區,放置準備寫出的數據
	PULONG			ioLength );  // 指向長度單元,輸入時為準備寫出的長度,返回后為實際寫出的長度


BOOL	WINAPI	CH375ResetAux(  // 復位輔助數據寫操作
	ULONG			iIndex );  // 指定CH375設備序號,必須是0


#ifdef __cplusplus
}
#endif

#endif		// _CH375_DLL_H