xsocketdoc.txt

組态软件设计与开发的配套源代码

XSocket ActiveX Controls

These codes are develped using VC++6.0, MFC4.2, on a Win2000. The source code for the 
following applications are distributed.
1. XSockServer.ocx
2. XSockClient.ocx
3. TcpClient.exe
4. XEchoServer.exe

1. XSockServer.ocx - This is a Server Control and can accept unlimited passive connections. 
It uses an internal communication object for each client connections and assigns a unique 
identifier. The container can communicate to the clients using this identifier.

2. XSockClient.ocx - This is a Client control and can make connection to only one server. If 
the user wants to make multiple connection then multiple controls has to be used for the 
application.

3. XEchoServer.exe -  This a sample echo server and it listens on port 7. This application 
accepts unlimited connections and echo's the received data back to the client. Uses 
XSockServer.ocx

4.TcpClient.exe -  This is a simple example Client program which connects to a listening 
Server. The user has to choose the machine name or IpAddress and port to connect to and can 
write and view the read data. Uses XSockClient.ocx.


To Register the control using the regsvr32 utility.
e.g.  
1. To register the ActiveX control  type in command prompt or run Regsvr32 XSockClient.ocx.
2. To unregister the ActiveX control  type in command prompt or run Regsvr32 /u XSockClient.ocx.

The controls have to be registered on the user system before using them or running the 
supplied example applications.


I. SockServerCtrl

METHODS:
1. BOOL Listen()
2. void Close()
3. BOOL Send(long lChildId, LPCTSTR lpData, long nDataLen);

Listen():
	Listens for an in coming connection at the LocalDotAddress and LocalPort specified 
by the user. Returns TRUE on success or FALSE on failure.

Send(long lChildId, LPCTSTR lpData, long nDataLen):
	lChildId: A unique long value which identifies the connection.
	lpData: The Data to be written to the socket
	nDataLen: The Byte length of the data to be written.
	Write to a connected socket which is identified by lChildId parameter. lChildId 
parameter is got from the OnAccept event which notifies the container that a passive 
connection is accepted now. Returns TRUE on success or FALSE 	on failure.

Close():
	Closes the server listening for passive connection.

PROPERTIES:
1. BSTR GetLocalAddress()
    void SetLocalAddress(LPCTSTR lpszNewValue)
2. long GetLocalPort()
    void SetLocalPort(long nNewValue)
3. BOOL GetNullTerminate()
    void SetNullTerminate(BOOL bNewValue)
4. long GetReceiveBufferCount()
    void SetReceiveBufferCount(long nNewValue)

LocalAddress:
	This property is of type string and is used by the Server Control to Listen and make 
a passive connection for an incoming connection. This is an optional property and if set 
it must be an IP address and not a machine Name.

LocalPort:
	This property is of type long and is used by the Server Control to Listen and make 
a passive connection for an incoming connection. This property must be set before calling 
Listen() method.

NullTerminate:
	This property is of type Boolean and when set TRUE appends a NULL to the end of the 
Byte Array to convert the data to a String.

ReceiveBufferCount:
	This property is of type long and sets the Buffer size for Reading data from the 
Socket. A non Zero positive value is accepted. A Buffer size greater than 8KB may not 
be accepted by Winsock. Default size of the buffer is 4096.

EVENTS:
1. void OnError(LPCTSTR lpErrorDescription)
2. void OnClose(long lChildId)
3. void OnReceive(long lChildId, LPCTSTR lpData, long nDataLen)
4. void OnAccept(long lChildId)

OnAccept(long lChildId):
	lChildId: The lChildId is a unique identifier which identifies the connection to a 
Client. 
	This event is fired when the server gets an incoming connection. The server passes a 
lChildId to the container. Any 	Read or Write to the socket will have to happen via this 
lChildId. 

OnError(LPCTSTR lpErrorDescription):
	lpErrorDescription: Network Error description.
	This event is fired when an error occurs in the socket communication.

OnReceive(long lChildId, LPCTSTR lpData, long nDataLen):
	lChildId: The lChildId is a unique identifier which identifies the connection to a Client. 
	lpData: The data is passed as parameter lpData and is of length nDataLen. This is not a 
NULL terminated string 	unless the NullTerminate property is set.  If the user wants to convert 
to a string then he has to convert it explicitly by assigning this byte array to a string data 
type and appending a NULL to it after nDataLen'th Byte.
	nDataLen: The length of the lpData in Bytes.
	This event is fired when data is received in the socket. 

OnClose(long lChildId):
	lChildId: The lChildId is a unique identifier which identifies the connection to a Client. 
	The active connection has closed the socket.


II. SockClientCtrl

METHODS:
1. BOOL Connect(LPCTSTR lpRemoteAddress, long nRemotePort)
2. long Send(LPCTSTR lpData, long nDataLen)
3. void Close()

Connect(LPCTSTR lpRemoteAddress, long nRemotePort):
	Makes an active connection to the specified RemoteAddress and RemotePort. If the 
connection is successful OnConnect() event gets fired. On error 
OnError(LPCTSTR lpErrorDescription) event gets fired. Returns TRUE on success or FALSE on 
failure.

Send(LPCTSTR lpData, long nDataLen):
	Writes the lpData of length nDataLen to the socket. The return type specifies the 
number of bytes successfully written 	to the socket. This no can be less of equal to the 
nDataLen parameter. Returns TRUE on success or FALSE on failure.

Close():
	Closes the active socket connection.

PROPERTIES:
1. BSTR GetLocalAddress()
   void SetLocalAddress(LPCTSTR lpszNewValue)
2. long GetLocalPort()
   void SetLocalPort(long nNewValue)
3. BOOL GetNullTerminate()
    void SetNullTerminate(BOOL bNewValue)
4. long GetReceiveBufferCount()
    void SetReceiveBufferCount(long nNewValue)

LocalAddress:
	This property is of type string and is used by the Server Control to Listen and make a 
passive connection for an incoming connection. This is an optional property and if set it 
must be an IP address and not a machine Name.

LocalPort:
	This is an optional property of type long and is used by the Client Control to create 
a socket.

NullTerminate:
	This property is of type Boolean and when set TRUE appends a NULL to the end of the 
Byte Array to convert the data to a String.

ReceiveBufferCount:
	This property is of type long and sets the Buffer size for Reading data from the 
Socket. A non Zero positive value is accepted. A Buffer size greater than 8KB may not be 
accepted by Winsock.

EVENTS:
1. void OnConnect()
2. void OnClose()
3. void OnSend()
4. void OnError(LPCTSTR lpErrorDescription)
5. void OnReceive(LPCTSTR lpData, long nDataLen)

OnConnect(): 
	Gets fired when the active connection is made successful.

OnClose(): 
	Gets fired when the server which made the passive connection closes its socket or is dead.

OnSend(): 
	Gets fired when the socket is ready to send data.

OnError(LPCTSTR lpErrorDescription):
	lpErrorDescription: Network Error description.
	This event is fired when an error occurs in the socket communication.

OnReceive(LPCTSTR lpData, long nDataLen):
	lpData: The data is passed as parameter lpData and is of length nDataLen. This is not a 
NULL terminated string 	unless the NullTerminate property is set. If the user wants to convert 
to a string then he has to convert it explicitly by assigning this byte array to a string data 
type and appending a NULL to it after nDataLen'th Byte.
	nDataLen: The length of the lpData in Bytes.
	This event is fired when data is received in the socket.