Copyright: Copyright (c) 1994 Gent Hito


IPPort Control
IPPort Control (Version 0.9)

Properties              Events              Error Codes              Copyright              Registration

IPPORT.VBX is free, but certain terms and conditions apply. Please refer to the Copyright section of this file (click on Copyright above) before using the control in your applications. Usage of IPPORT.VBX indicates that you have read and agreed to the terms and conditions of the Copyright Notice supplied therein.

Description

This is the first release (0.9) of IPPORT.VBX. It must be considered as a late Beta. Version 1.0 will be available after the control has been more widely tested.

IPPORT.VBX facilitates TCP/IP communications by providing an easy interface to WINSOCK functions. The current version of the control allows a client application to communicate with a server using stream (TCP/IP) sockets.

File Name

IPPORT.VBX

Object Type

IPPort

Remarks

The operation of the control is almost completely asynchronous. All the calls except the ones that deal with host and address resolution, operate through Windows messages (no blocking calls!!). The gain in performance is considerable when compared to using blocking calls.

The first and foremost requirement in designing the control was ease of use. The control has a minimum of properties, and four events: Connected, ReadyToSend, DataIn, and Disconnected. The events are relatively self-explanatory. The connection is attempted by setting the Connected property to true, and then waiting for the Connected event. The destination is defined by setting the Port property and either the HostName or the HostAddress property. Data is sent by assigning the data string to the DataToSend property.

Besides the properties described in the previous paragraph, there are three more properties:  EOL, InBufferSize and OutBufferSize. The first one is used to break the incoming data in chunks separated by the value of the EOL string. The other two set the buffer sizes for the internal Winsock queues.

This pretty much sums it up folks! The rest of this file describes the properties in a little bit more detail. Good luck!!

_________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________

If you would like to register your copy, please send a mailing address to any of the addresses provided below. If you provide an email address, you will be notified about future versions and/or bug fixes.

If you don't have an email address, you can send me a SASE (self-addressed-stamped-envelope) and I will send you any information whenever it is available. Contact information follows. Please use the same address for bug reports, suggestions, comments, questions. I will try to answer as soon as I can.

GENT  HITO	INTERNET:	ghito@bvcd.csc.ncsu.edu

642 Chappell Drive 	COMPUSERVE:	Gent Hito 73744,2070

Raleigh, NC 27606

U.S.A.

_________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________


Copyright Notice

IPPORT.VBX is Copyrighted (1994) by Gent Hito, referred to below as 'the author'. By using the IPort Control you implicitly indicate that you have read and agreed to the following terms:

You may:

- Use IPPORT.VBX in your development environment.

- Freely copy and distribute it as long as this Copyright Notice is distributed with it and the copy is provided to the third party FREE OF CHARGE.

- Freely distribute it as a RUNTIME component of  your applications. The author asks for NO royalties or run-time fees. Also, this help file and accompanying demos do not have to be included in your distribution package.

You may NOT:

- Modify IPPORT.VBX, and this help file in any way.

- Remove any proprietary notices, labels, or marks on the program and accompanying documentation (help file).

- Sell or resell IPPORT.VBX and/or any of its accompanying products and documentation, by itself or as part of another package, except as a RUNTIME component of another application whose primary purpose is NOT illustration of the functionality of IPPORT.VBX.

Limitation of liability:

The author of IPPORT.VBX makes no warranties, expressed or implied, in relation to this product. In no event shall the author be liable to you for any damages, including any loss of profits, loss of data, including but not limited to special, incidental, consequential, or indirect damages arising from the use of this software.

Registration:

If you would like to register your copy, please send a mailing address to any of the addresses provided below. If you provide an email address, you will be notified about future versions and/or bug fixes.

If you don't have an email address, you can send me a SASE (self-addressed-stamped-envelope) and I will send you any information whenever it is available. Contact information follows. Please use the same address for bug reports, suggestions, comments, questions. I will try to answer as soon as I can.

GENT  HITO	INTERNET:	ghito@bvcd.csc.ncsu.edu

642 Chappell Drive 	COMPUSERVE:	Gent Hito 73744,2070

Raleigh, NC 27606

U.S.A.


Registration Information

If you would like to register your copy, please send a mailing address to any of the addresses provided below. If you provide an email address, you will be notified about future versions and/or bug fixes.

If you don't have an email address, you can send me a SASE (self-addressed-stamped-envelope) and I will send you any information whenever it is available. Contact information follows. Please use the same address for bug reports, suggestions, comments, questions. I will try to answer as soon as I can.

GENT  HITO

642 Chappell Drive

Raleigh, NC 27606

U.S.A.

INTERNET:	ghito@bvcd.csc.ncsu.edu

COMPUSERVE:	Gent Hito 73744,2070


Events

*Connected

*DataIn

*Disconnected

*ReadyToSend


Properties

*Connected

*DataToSend

*EOL

*HostAddress

*HostName

*InBufferSize

Index

Left

Name

*OutBufferSize

*Port

Top


Connected Property

Description

Setting the property to True initiates a connection request. Setting it to False breaks the current connection (if any).

Usage

[form.][ipportcontrol.]Connected[ = value]

Default Value

False

Remarks

Connected is an Action property. Use it to create and destroy connections. Before initiating a connection, make sure that the HostName (or HostAddress) and Port properties are set to the appropriate values. Otherwise, an error will occurr.

After setting the property to True, wait for the Connected or ReadyToSend event before sending out any data.

Data Type

Boolean (Integer)


DataToSend Property

Description

DataToSend is an Action property. Assigning a Visual Basic string to this property makes the control send the string to the remote host.

Usage

[form.][ipportcontrol.]EOL[ = value]

Default Value

"" (empty string)

Remarks

If the data cannot be sent, an error is fired. Use the OnError statement to trap errors.

Setting this property to a large string can fill up the outgoing queue. If this happens, trap the error properly, and the wait for the ReadyToSend event before attempting to send the data again.

If the error is repeated, than make sure that OutBufferSize is larger than the length of your string, and increase OutBufferSize, or decrease the length of your string accordingly.

Data Type

String


EOL Property

Description

Used to break the incoming data stream into chunks separated by the string assigned to EOL. For more information, see the DataIn Event.

Usage

[form.][ipportcontrol.]EOL[ = value]

Default Value

"" (empty string)

Remarks

The EOL property is especially useful with ASCII files. Setting it to Chr$(10) (newline) helps converting the incoming stream to MSDOS ASCII (CRLF ended lines).

Data Type

String


HostAddress Property

Description

Specifies the remote host IP number in internet dotted format.

Usage

[form.][ipportcontrol.]HostAddress[ = value]

Default Value

0.0.0.0

Remarks

HostAddress is an action property. Setting it to a string value intiaties a domain name resolution call (in blocking mode). After the call completes, the corresponding IP address (domain name) can be found in the HostName property.

Data Type

String


HostName Property

Description

Specifies the remote host domain name.

Usage

[form.][ipportcontrol.]HostName[ = value]

Default Value

"" (empty string)

Remarks

HostName is an action property. Setting it to a string value intiaties a domain name resolution call (in blocking mode). After the call completes, the corresponding IP number can be found in the HostAddress property.

Data Type

String


InBufferSize Property

Description

Specifies the size (in bytes) of the receiving queue in the underlying TCP/IP provider.

Usage

[form.][ipportcontrol.]InBufferSize[ = value]

Default Value

2048

Remarks

This is the size of an internal queue in the TCP/IP provider. Increase or decrease the size depending on the amount of data that you will be receiving. Increasing InBufferSize can provide drastic improvements in performance in some cases.

Data Type

Integer


OutBufferSize Property

Description

Specifies the size (in bytes) of the outgoing queue in the underlying TCP/IP provider.

Usage

[form.][ipportcontrol.]OutBufferSize[ = value]

Default Value

2048

Remarks

This is the size of an internal queue in the TCP/IP provider. Increase or decrease the size depending on the size of data chunks that you will be sending.

Data Type

Integer


Port Property

Description

Specifies the IP port of the remote host.

Usage

[form.][ipportcontrol.]Port[ = value]

Default Value

0

Remarks

The Port property must be set before a connection is attempted. The Port cannot be changed once a connection is made. Any attempt to set the Port property when a connection is active will generate an error.

Data Type

Integer


Connected Event

Description

Occurs when a connection is made to the remote host.

Syntax

Sub ipportcontrol_Connected(StatusCode As Integer, Description As String)

Remarks

If the connection succeeds, StatusCode is 0, and Description is "OK".

If the connection fails for any reason, StatusCode has the error code returned by Winsock. Description contains a description of this code. The value of StatusCode is obtained by adding 15001 to the corresponding Winsock error code.

Please refer to the Error Codes section for more information.


DataIn Event

Description

Occurs when data arrives from the remote host.

Syntax

Sub ipportcontrol_DataIn(Text As String, EOL As Integer)

Remarks

Trapping the DataIn event is your only chance to get the data coming from the other end of the connection. The incoming data are given in Text. Text is a Visual Basic string, and as such might be considered as a binary chunk of data with length Len(Text).

EOL indicates whether an EOL string was found on the end of Text or not. If the EOL string was found, than EOL is True. If Text was obtained is the end of a chunk of data received from Winsock, then EOL is False. Please note that this also means that more than one DataIn event with EOL set to False can be received during a connection.

If the EOL property is "" (empty), then EOL can be disregarded. For more information on EOL, please refer to the description of the EOL property.


Disconnected Event

Description

Occurs when the connection to the remote host is closed(broken).

Syntax

Sub ipportcontrol_Disonnected(StatusCode As Integer, Description As String)

Remarks

If the connection is broken normally, StatusCode is 0, and Description is "OK".

If the connection is broken for any other reason, StatusCode has the error code returned by Winsock. Description contains a description of this code. The value of StatusCode is obtained by adding 15001 to the corresponding Winsock error code.

Please refer to the Error Codes section for more information.


ReadyToSend Event

Description

Indicates that the underlying TCP/IP subsystem is ready to receive data.

Syntax

Sub ipportcontrol_ReadyToSend()

Remarks

If the connection succeeds, StatusCode is 0, and Description is "OK".

If the connection fails for any reason, StatusCode has the error code returned by Winsock. Description contains a description of this code. The value of StatusCode is obtained by adding 15001 to the corresponding Winsock error code.

Please refer to the Error Codes section for more information.


Error Codes

The following is a list of the trappable errors fired by IPPort:

IPPort Internal Errors

20101	You cannot change the Port at this time. Close the connection first.

20102	You cannot change the HostName at this time. Close the connection first..

20103	You cannot change the HostAddress at this time. Close the connection first.

20104	Already connected. Close the current connection first in order to reconnect..

Winsock Errors

(NOTE: The value of the corresponding Winsock error code can be obtained by subtracting 15001 to the error code given here).

     25005	(WSAEINTR)	Interrupted system call.

     25010	(WSAEBADF)	Bad file number.

     25014	(WSAEACCES)	Access denied.

     25015	(WSAEFAULT)	Bad address.

     25023	(WSAEINVAL)	Invalid argument.

     25025	(WSAEMFILE)	Too many open files.

     25036	(WSAEWOULDBLOCK)	Operation would block.

     25037	(WSAEINPROGRESS)	Operation now in progress.

     25038	(WSAEALREADY)	Operation already in progress.

     25039	(WSAENOTSOCK)	Socket operation on non-socket.

     25040	(WSAEDESTADDRREQ)	Destination address required.

     25041	(WSAEMSGSIZE)	Message too long.

     25042	(WSAEPROTOTYPE)	Protocol is wrong type for socket.

     25043	(WSAENOPROTOOPT)	Bad protocol option.

     25044	(WSAEPROTONOSUPPORT)	Protocol not supported.

     25045	(WSAESOCKTNOSUPPORT)	Socket type not supported.

     25046	(WSAEOPNOTSUPP)	Operation not supported on socket.

     25047	(WSAEPFNOSUPPORT)	Protocol family not supported.

     25048	(WSAEAFNOSUPPORT)	Address family not supported by protocol family.

     25049	(WSAEADDRINUSE)	Address already in use.

     25050	(WSAEADDRNOTAVAIL)	Can't assign	requested address.

     25051	(WSAENETDOWN)	Network is down.

     25052	(WSAENETUNREACH)	ICMP network unreachable.

     25053	(WSAENETRESET)	Network was reset.

     25054	(WSAECONNABORTED)	Software caused connection abort.

     25055	(WSAECONNRESET)	Connection reset by peer.

     25056	(WSAENOBUFS)	No buffer space is supported.

     25057	(WSAEISCONN)	Socket is already connected.

     25058	(WSAENOTCONN)	Socket is not connected.

     25059	(WSAESHUTDOWN)	Can't send after socket shutdown.

     25060	(WSAETOOMANYREFS)	Too many references.

     25061	(WSAETIMEDOUT)	Connection timed out.

     25062	(WSAECONNREFUSED)	Connection refused.

     25063	(WSAELOOP)	Too many levels of symbolic links.

     25064	(WSAENAMETOOLONG)	Name too long.

     25065	(WSAEHOSTDOWN)	Host is down.

     25066	(WSAEHOSTUNREACH)	Host is unreachable.

     25067	(WSAENOTEMPTY)	Directory not empty.

     25068	(WSAEPROCLIM)	EPROCLIM returned.

     25069	(WSAEUSERS)	EUSERS returned.

     25070	(WSAEDQUOT)	Disk quota exceeded.

     25071	(WSAESTALE)	ESTALE returned.

     25072	(WSAEREMOTE)	The object is remote.

     25092	(WSASYSNOTREADY)	System not ready.

     25093	(WSAVERNOTSUPPORTED)	Version is not supported.

     25094	(WSANOTINITIALISED)	Not initialized.

     26002	(WSAHOST_NOT_FOUND)	Host not found.

     26003	(WSATRY_AGAIN)	Try again.

     26004	(WSANO_RECOVERY)	Non recoverable error.

     26005	(WSANO_DATA)	No data record available.