readme.txt

招商银行商户开发包For Win32.zip

		Read me

This is a module which implements some internet operations.
Linking this module,your applications can cooperate with China Merchants Bank's Internet Payment System automatically.

Usage:
  A.Use as Dll:
	If you want to use the FirmClient module as Dll,you should complete
	the following steps:
		1. Copy the file named FirmClient.dll to your system directory.
			On Windows 95/98/NT/2000/XP,the system directory is <WinRoot>\system32.
		2. If your program language is C or C++,please
			. Declear a HMODULE variable;
			. Invoke system function ::LoadLibrary to load this Dll;
			. Declear function points which point the functions you need;
			. Invoke system functin ::GetProcAddress to get the address of function points;
			. Use the function points to call corresponding functions;
			. After completing your task,Invoke system function ::FreeLibrary to release FirmClient.dll.
		3. If your program language is NOT C or C++,such as VB,Java,etc,please
			see the specific language's document on how to use Dll.
  B.Use as Lib
	If you want to use the FirmClient module as Lib,your program language must be C or C++
	and complet the following steps:
		1. Copy the file named FirmClient.dll to your system directory.
			On Windows 95/98/NT,the system directory is <WinRoot>\system32.
		2. Include the head file FirmClientAPI.h in your .c or .cpp file;
		3. Tell your C or C++ linker where to find FirmClient.lib;
		4. Call functions listed in FirmClientAPI.h to complet your task.

////////////////////////////////////////////////////////////////////////////////////

Samples:
  A.Use as DLL(For C or C++)
	void SampleFun()
	{
		HMODULE hDllModule;
		int (*pLoginC)(char*,char*,char*);
		int (*pSetOptions)(char*,char*,char*);
		int (*pLogout)();
		int (*pSettlePartOrder)(char*,char*,char*,char*);
		int (*pSettleOrder)(char*,char*,char*);
		int (*pQuerySettledOrder)(char*,char*,char**);
		int (*pQueryUnsettledOrder)(char**);
		int (*pFreeBuffer)(char*);
		char* (*pGetLastErr)(int);

		hDllModule=::LoadLibrary("FirmClient.dll");
		if(hDllModule == NULL)
		{
			return;
		}

		char* pErr;
		pSetOptions=(int (*)(char*,char*,char*))::GetProcAddress(hDllModule,"SetOptions");
		pLoginC=(int (*)(char*,char*,char*))::GetProcAddress(hDllModule,"LoginC");
		pLogout=(int (*)())::GetProcAddress(hDllModule,"Logout");
		pSettleOrder=(int (*)(char*,char*,char*))::GetProcAddress(hDllModule,"SettleOrder");
		pSettlePartOrder=(int (*)(char*,char*,char*,char*))::GetProcAddress(hDllModule,"SettlePartOrder");
		pQuerySettledOrder=(int (*)(char*,char*,char**))::GetProcAddress(hDllModule,"QuerySettledOrder");
		pQueryUnsettledOrder=(int (*)(char**))::GetProcAddress(hDllModule,"QueryUnsettledOrder");
		pFreeBuffer=(int (*)(char*))::GetProcAddress(hDllModule,"FreeBuffer");
		pGetLastErr=(char* (*)(int))::GetProcAddress(hDllModule,"GetLastErr");

		if(pSetOptions == NULL)
		{
			::FreeLibrary(hDllModule);
			return;
		}

		int nRet=(*pSetOptions)("www.cmbchina.com",NULL,NULL);
		pErr = pGetLastErr(nRet);

		if(pLoginC == NULL)
		{
			::FreeLibrary(hDllModule);
			return;
		}

		nRet=(*pLoginC)("0755","000107","888888");
		if(nRet != 0)
		{
			pErr = pGetLastErr(nRet);
			AfxMessageBox(pErr);
			::FreeLibrary(hDllModule);
			return;
		}

		if(pQuerySettledOrder != NULL)
		{
			int nRet;
			char* pBuf;
			nRet=(*pQuerySettledOrder)("20010801","20010831",&pBuf);

			if(nRet != 0)
			{
				pErr = pGetLastErr(nRet);
			}
			else
			{
				//Any code to operate settled order information by pBuf
				pFreeBuffer(pBuf);
			}
		}

		if(pQueryUnsettledOrder != NULL)
		{
			int nRet;
			char* pBuf;
			nRet=(*pQueryUnsettledOrder)(&pBuf);

			if(nRet != 0)
			{
				pErr = pGetLastErr(nRet);
			}
			else
			{
				//Any code to operate unsettled order information by pBuf,such as settle order,cancel order,part settle order
				pFreeBuffer(pBuf);
			}
		}

		if(pLogout != NULL)
		{
			int nRet=(*pLogout)();
			pErr = pGetLastErr(nRet);
		}

		::FreeLibrary(hDllModule);
}

  B.Use as Lib(For C or C++ only)
	#include "FirmClientAPI.h"
	  
	void SampleFunc()
	{
		INET_STATUS isRet;
		char* pErr;
	
		isRet = SetOptions("www.cmbchina.com",NULL,NULL);
		if(isRet != INET_SUCCESS)
		{
			pErr = GetLastErr(isRet);
			return;
		}

		isRet = LoginC("0755","000107","017675");
		if(isRet != INET_SUCCESS)
		{
			pErr = GetLastErr(isRet);
			return;
		}

		char* pBuf;
		isRet=QuerySettledOrder("20010801","20010831",&pBuf);

		if(isRet != 0)
		{
			pErr = GetLastErr(isRet);
		}
		else
		{
			//Any code to operate settled order information by pBuf
			FreeBuffer(pBuf);
		}

		isRet=QueryUnsettledOrder(&pBuf);
		if(isRet != 0)
		{
			pErr = GetLastErr(isRet);
		}
		else
		{
			//Any code to operate unsettled order information by pBuf,such as settle order,cancel order,part settle order
			FreeBuffer(pBuf);
		}
		
		isRet = Logout();
		if(isRet != INET_SUCCESS)
		{
			pErr = GetLastErr(isRet);
			return;
		}
	}

////////////////////////////////////////////////////////////////////////////////////

enum INET_STATUS
{
	INET_SUCCESS,
	INET_COMMUNICATION_FAILURE,
	INET_ALREADY_LOGIN,
	INET_NOT_LOGIN,
	INET_LOGIN_FAILURE,
	INET_LOGOUT_FAILURE,
	INET_INPUTPARA_ERROR,
	INET_CANNOT_QUERYONEORDER,
	INET_CANNOT_QUERYSETTLEDORDER,
	INET_CANNOT_QUERYCOUNT,
	INET_CANNOT_QUERYUNSETTLEDORDER,
	INET_CANNOT_SETTLEORDER,
	INET_CANNOT_FIND_PUBLICKEYFILE,
	INET_MESSAGE_UNTRUTHFUL,
	INET_UNKOWN_FAILURE
};

//This function must be invoked first to set Web server and proxy properties.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
extern "C" INET_STATUS WINAPI EXPORT __stdcall SetOptions(
		char* pszHttpServer,				//Input.Web server name.For example,"www.cmbchina.com"
		char* pszPort = NULL,				//Input.Web server port.The default HTTP port is 80.
		char* pszProxyIP = NULL);			//Input.Proxy server IP address if you connect to Internet through proxy,otherwise NULL or ""
														   
//This function should be invoked to login.Only you have loged in successfully,direct connecting functions below may be called.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
//Note:If the bank you opened an account in has no individual web server,you must call this function.In this case,you can NOT call Login().
//If you don't know whether your bank has individual web server,please ask administrator of bank.
//Recommended.
extern "C" INET_STATUS WINAPI EXPORT __stdcall LoginC(
		char* pszBranchID,					//Input.ID of bank.Please get it from administrator of bank
		char* pszCoNo,						//Input.Firm ID,6 characters
		char* pszPwd);						//Input.Password

//When you complete task,this function should be invoked.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
extern "C" INET_STATUS WINAPI EXPORT __stdcall Logout();

//Get settled order information.The span of date can not beyond ONE month.
//Note:The information saved in pszBuf is made up of continuous order records.After calling this function,
//you must call FreeBuffer() to free the memory allocated by this function.
//	Every order record has following parts:
//		Transaction date-----------"yyyymmdd"
//		Processed date-------------"yyyymmdd"
//		Amount---------------------"*****.**"
//		Bill No.-------------------6 characters
//		Bill status----------------1 characters
//	Every part is separated by '\n'.The bill status="0" means settled,"1" means canceled,"2" means part settled.
//	For example,returned information may be "19980820\n19980920\n1200.00\n100201\n1\n19980830\n19980830\n200.00\n100201\n2\n".
//	This information includes two order information records.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
extern "C" INET_STATUS WINAPI EXPORT __stdcall QuerySettledOrder(
		char*  pszBeginDate,				//Input.Date of beginning
		char*  pszEndDate,					//Input.Date of end
		char** ppszBuf);					//Output.To save settled orders' information


//Get unsettled order information.
//Note:The information saved in pszBuf is made up of continuous order records.After calling this function,
//you must call FreeBuffer() to free the memory allocated by this function.
//	Every order record has following parts:
//		Transaction date-----------"yyyymmdd"
//		Amount---------------------"*****.**"
//		Bill No.-------------------6 characters
//		Reference No.--------------20 characters
//	Every part is separated by '\n'.
//	For example,returned information may be "19980820\n1200.00\n100201\n98082000010700030001\n19980830\n200.00\n100201\n98083000010700030009\n".
//	This information includes two order information records.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
extern "C" INET_STATUS WINAPI EXPORT __stdcall QueryUnsettledOrder(
		char** ppszBuf);						//Output.To save unsettled orders' information

//Settle one order.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
extern "C" INET_STATUS WINAPI EXPORT __stdcall SettleOrder(
		char* pszCoNo,						//Input.Firm ID
		char* pszBillNo,					//Input.Order bill No.
		char* pszRefNo);					//Input.Reference No.This item can be gotten by calling QueryUnsettledOrder

//Settle part of order.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
extern "C" INET_STATUS WINAPI EXPORT __stdcall SettlePartOrder(
		char* pszCoNo,						//Input.Firm ID
		char* pszBillNo,					//Input.Order bill No.
		char* pszRefNo,						//Input.Reference No.This item can be gotten by calling QueryUnsettledOrder
		char* pszPartAmount);				//Input.Part amount of this order.The part amount can NOT be larger than the original value.

//Cancel one order.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
extern "C" INET_STATUS WINAPI EXPORT __stdcall CancelOrder(
		char* pszCoNo,						//Input.Firm ID
		char* pszBillNo,					//Input.Order bill No.
		char* pszRefNo);					//Input.Reference No.This item can be gotten by calling QueryUnsettledOrder

//Check whether the notice message from bank is trusted or not.
//This function may be evoked alone.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
extern "C" INET_STATUS WINAPI EXPORT __stdcall CheckInfoFromBank(
		char* pszPublickeyFilePath,			//Input.Pathname of Publickey file like "C:\\PubKey\\CMBPK.key"
		char* pszMsg);						//Input.Message sent from bank like "Succeed=..&BillNo=..&Amount=..&Date=..&Msg=..&signature=.."

//Free the memory which is allocated by QuerySettledOrder or QueryUnsettledOrder
//Note:After you invoked QuerySettledOrder or QueryUnsettledOrder,you MUST call this function to
//free the memory.Or your system will produce Memory leak.
//Retuen:INET_STATUS,indicates whether the calling is success or failed.
extern "C" INET_STATUS WINAPI EXPORT __stdcall FreeBuffer(
		char* pBuffer);						//Input.Memory allocated by QuerySettledOrder or QueryUnsettledOrder

//Get last error message.
//This function should be invoked after every unsuccessfully calling to get error message.
//Return:A point to a char string describes error message.
extern "C" char* WINAPI EXPORT __stdcall GetLastErr(
		INET_STATUS isNo);				//Input.The returned INET_STATUS variable of last calling