Copyright: Helpfile Generated by VB HelpWriter!


Main

  dsSocket Winsock Control

Properties	Events	Error Codes	About

Description

The dsSocket custom control provides support for TCP/IP network communications using Visual Basic.  The control utilizes the Windows Sockets (Winsock) standard.

Object Type

WinSock

Remarks

The Windows socket control provides the capability of communicationg as either a client process or a server process depending on the specified action for that particular socket.  Properties are utilized to setup the communication parameters and initiate the connection.  While connected events are provided that inform the programmer of changes in the connection status as well as data availability.

The standard Visual Basic variables Err and Error are used to return error status from property modification.  The Exception event provides information regarding asynchronous errors.

A client connection can be established with only a few lines of code as shown below:

dsSocket1.RemoteHost = "Washington"

dsSocket1.RemotePort = 7

dsSocket1.Action = 0

dsSocket1.Send = "Testing 1... 2... 3..."

dsSocket1.Action = 2

In this sample the Receive event would be fired and the ReceiveData would contain an echo of the data placed in the Send property.

Distribution

Registered product owners are licensed to distribute the DSSOCK.VBX file with their applications.  Under no circumstance are you permitted to distribute the DSSOCK.LIC file.


Properties

All of the properties for this control are listed in the following table. Properties that apply only to this control, or that require special consideration when used with it, are marked with an asterisk (*). For documentation of the remaining properties, see Appendix A, "Standard Properties, Events, and Methods," in the Custom Control Reference.

About	*Linger	*RemotePort	Top

*Action	*LocalDotAddr	*Send

*BytesSent	*LocalName	*ServiceName

*DataSize	*LocalPort	*Socket

Enabled	Name	*State

Index	*RemoteDotAddr	Tag

Left	*RemoteHost	*Timeout


Events

All of the events for this control are listed in the following table. Events that apply only to this control, or that require special consideration when used with it, are marked with an asterisk (*). For documentation of the remaining events, see Appendix A, "Standard Properties, Events, and Methods," in the Custom Control Reference.

*Accept	*Connect	*Listen	*SendReady

*Close	*Exception	*Receive


  About

The dsSocket Visual Basic Custom Control was developed by Dolphin Systems Inc. to provide network communications using the Winsock standard.  For additional information you may contact the developer directly at:

Dolphin Systems Inc.

13584 Kennedy Rd. N.,

Inglewood, Ontario

CANADA   L0N 1K0

(905) 838-2896

(905) 838-0649  FAX

Compuserve:	70471,137

Internet:	stephenc@idirect.com


Action

Description

Specifies Connect, Listen or Close operation on a socket.

Syntax

[form.]dsSocket1.Action = setting%

Remarks

The Action properties specifies a change in state for the specified socket.  The following table details valid Action property values.

Value	Action

SOCK_ACTION_CLOSE	1	Close an existing connection

SOCK_ACTION_CONNECT	2	Establish a connection

SOCK_ACTION_LISTEN	3	Listen for incoming connection

Data Type

Integer

See Also

LocalPort    RemoteDotAddr    RemoteHost    RemotePort    ServiceName


BytesSent

Description

Returns the number of bytes transferred.

Syntax

[form.]dsSocket1.BytesSent

Remarks

Returns the number of bytes transferred in the last Send.  If an error occurred in sending the data then the BytesSent property will return zero.  Read only at run-time.  Not available at design-time.

Data Type

Integer

See Also

Send


DataSize

Description

Sets and returns the maximum number of bytes to transfer.

Syntax

[form.]dsSocket1.DataSize [ = setting% ]

Remarks

Sets and returns the maximum number of bytes to be transferred from the network to the Receive event.  The minimum value for DataSize is 100 and the maximum is 32767.  The default value is 2048.  Global memory of DataSize bytes is allocated for receiving incoming data buffers.

Data Type

Integer

See Also

Receive


RemoteHost

Description

Sets and returns the name of the remote computer.

Syntax

[form.]dsSocket1.RemoteHost [ = setting$ ]

Remarks

The RemoteHost property may be set the network name of the remote computer to connect to.  If the RemoteDotAddr property is empty the dsSocket control will use the RemoteHost property to determine the network address for out-going connections.  The RemoteHost name must either be contained in the HOSTS file or a name resoultion service (e.g.: DNS) must be available to resolve the network address of the remote computer.

Data Type

String

See Also

Action    RemoteDotAddr


RemoteDotAddr

Description

Sets and returns the IP address of server for establishing a connection.

Syntax

[form.]dsSocket1.RemoteDotAddr [ = setting$ ]

Remarks

The RemoteDotAddr property accepts a string in standard IP address dot notation (e.g.: 120.20.24.12) that will be used when making a connection.  If an IP address is provided the control will not perform a name lookup when connecting to a server.  If name resolution services are not available for a wide-area network use the RemoteDotAddr to provide the connection information.  On a local-area network you can use either the RemoteHost or RemoteDotAddr property.  The IP address must contain four numbers seperated by periods.

Data Type

String

See Also

Action    RemoteHost


RemotePort

Description

Sets and returns the port number to connect to.

Syntax

[form.]dsSocket1.RemotePort [ = setting% ]

Remarks

Sets and returns the network port number that will be utilized for establishing connections.  When setting the Action property to SOCK_ACTION_CONNECT, the RemotePort number must equate to a port number with a Listen active on the remote computer.  If the RemotePort property is set to zero the ServiceName property will be used to resolve a port number for connections.

Data Type

Integer

See Also

Action    RemoteHost    ServiceName


LocalName

Description

Returns the network name of the local computer.

Syntax

[form.]dsSocket1.LocalName

Remarks

Returns the network name of the local computer as defined in the network configuration parameters.  Read only at run-time and design-time.

Data Type

String

See Also

LocalDotAddr


LocalPort

Description

Sets and returns the port number used on the local computer.

Syntax

[form.]dsSocket1.LocalPort [ = setting% ]

Remarks

Sets and returns the network port number that will be used for incoming connections.  When the dsSocket control is in Listen mode a client application can connect to the computer by specifying this port number as its RemotePort.  If the LocalPort property is set to zero then the ServiceName property will be used to resolve a port number for network Listen's.

Data Type

Integer

See Also

Action    RemotePort    ServiceName


ServiceName

Description

Sets and returns the name of the network service to use.

Syntax

[form.]dsSocket1.ServiceName [ = setting$ ]

Remarks

Sets and returns the name of the network service that will be utilized for incoming Listen's and outgoing Connect's.  This name is converted to a port number on the local computer by accessing the services data file or a service name resolution process.  The ServiceName may be used in place of specifying the RemotePort or LocalPort properties.  This property setting will be ignored if the RemotePort (connect) or LocalPort (listen) properties are non-zero.

Data Type

String

See Also

Action    LocalPort    RemotePort


Error Codes

The following table lists the trappable errors for the dsSocket custom control.

Error Variable	Number	Explanation

SOCK_ERR_CLOSED	20000	Connection closed

SOCK_ERR_MEMORY	20001	Memory allocation error

SOCK_ERR_ISCLOSED	20002	Socket is already closed

SOCK_ERR_ISLISTEN	20003	Socket is aready listening

SOCK_ERR_NOPORT	20004	No port number or service name specified

SOCK_ERR_INTR	21004	Interrupted system call

SOCK_ERR_BADF	21009	Bad file number

SOCK_ERR_ACCES	21013	Permission denied

SOCK_ERR_FAULT	21014	Bad address

SOCK_ERR_INVAL	21022	Invalid argument

SOCK_ERR_MFILE	21024	Too many open files

SOCK_ERR_WOULDBLOCK	21035	Operation would block

SOCK_ERR_INPROGRESS	21036	Operation now in progress

SOCK_ERR_ALREADY	21037	Operation already in progress

SOCK_ERR_NOTSOCK	21038	Socket operation on non-socket

SOCK_ERR_DESTADDRREQ	21039	Destination address required

SOCK_ERR_MSGSIZE	21040	Message too long

SOCK_ERR_PROTOTYPE	21041	Protocol wrong type for socket

SOCK_ERR_NOPROTOOPT	21042	Bad protocol option

SOCK_ERR_PROTONOSUPPORT	21043	Protocol not supported

SOCK_ERR_SOCKTNOSUPPORT	21044	Socket type not supported

SOCK_ERR_OPNOTSUPP	21045	Operation not supported on socket

SOCK_ERR_PFNOSUPPORT	21046	Protocol family not supported

SOCK_ERR_AFNOSUPPORT	21047	Address family not supported by protocol family

SOCK_ERR_ADDRINUSE	21048	Address already in use

SOCK_ERR_ADDRNOTAVAIL	21049	Can't assign requested address

SOCK_ERR_NETDOWN	21050	Network is down

SOCK_ERR_NETUNREACH	21051	Network is unreachable

SOCK_ERR_NETRESET	21052	Net dropped connection or reset

SOCK_ERR_CONNABORTED	21053	Software caused connection abort

SOCK_ERR_CONNRESET	21054	Connection reset by peer

SOCK_ERR_NOBUFS	21055	No buffer space available

SOCK_ERR_ISCONN	21056	Socket is already connected

SOCK_ERR_NOTCONN	21057	Socket is not connected

SOCK_ERR_SHUTDOWN	21058	Can't send after socket shutdown

SOCK_ERR_TOOMANYREFS	21059	Too many references, can't splice

SOCK_ERR_TIMEDOUT	21060	Connection timed out

SOCK_ERR_CONNREFUSED	21061	Connection refused

SOCK_ERR_LOOP	21062	Too many levels of symbolic links

SOCK_ERR_NAMETOOLONG	21063	File name too long

SOCK_ERR_HOSTDOWN	21064	Host is down

SOCK_ERR_HOSTUNREACH	21065	No Route to Host

SOCK_ERR_NOTEMPTY	21066	Directory not empty

SOCK_ERR_PROCLIM	21067	Too many processes

SOCK_ERR_USERS	21068	Too many users

SOCK_ERR_DQUOT	21069	Disc Quota Exceeded

SOCK_ERR_STALE	21070	Stale NFS file handle

SOCK_ERR_REMOTE	21071	Too many levels of remote in path

SOCK_ERR_SYSNOTREADY	21091	Network SubSystem is unavailable

SOCK_ERR_VERNOTSUPPORTED	21092	WINSOCK DLL Version out of range

SOCK_ERR_NOTINITIALISED	21093	Successful WSASTARTUP not yet performed

SOCK_ERR_HOST_NOT_FOUND	22001	Host not found

SOCK_ERR_TRY_AGAIN	22002	Non-Authoritative Host not found

SOCK_ERR_NO_RECOVERY	22003	Non-Recoverable errors: FORMERR, REFUSED, NOTIMP

SOCK_ERR_NO_DATA	22004	Valid name, no data record of requested type


Send

Description

Sets the data for sending on the network.

Syntax

[form.]dsSocket1.Send = setting$

Remarks

Setting the Send property to a string will cause the data to be sent over the network.  To send data the socket must be in a connected state.  The maximum string size for the Send property is 32767 characters, a limit of the WinSock 1.1 specification.  Data blocks larger than 32767 must be broken down for network transfers.  The Winsock network support will attempt to send the data immediately.  If this is not possible then the error SOCK_ERR_WOULDBLOCK will be returned and the SendReady event will occur when the network is again ready for data transfer.  You can use this event to set the data into the Send property again.

Example:	dsSocket1.Send = "This is my information."

' this will send a string, the other end of the connection will get a Receive event

' with the string passed in the ReceiveData parameter

Data Type

String

See Also

Receive    SendReady


Receive

Description

Indicates that data has been received on a connection.

Syntax

Sub dsSocket_Receive ( [ Index As Integer, ] ReceiveData As String )

Remarks

The Receive event occurs whenever a connected process sends data.  The data is contained in the ReceiveData parameter.  The length of the data string will not exceed the value specified in the DataSize property.  The network is not required to transfer data in the same buffer sizes that they were sent in from the connected process.  Partial or multiple buffers can arrive in the ReceiveData parameter.  The normal method for processing the Receive event is to add the data to a predefined string and process the data when the required amount has been received.

Example:

Global szData	As String

Sub Receive( Index as Integer, ReceiveData as String )

szData = szData + ReceiveData

If ( Len(szData) > 100 ) Then

Call ProcessData( Left( szData, 100 ) )

szData = Mid( szData, 101 )

End If

End Sub

See Also

DataSize    Send


SendReady

Description

Indicates the network is ready to transfer data.

Syntax

Sub dsSocket_SendReady ( [ Index As Integer ] )

Remarks

The SendReady event occurs when the network sub-system changes from a not-ready state to a ready state.  When sending data, if the network is not ready the error SOCK_ERR_WOULDBLOCK is returned.  When the network is again ready the SendReady event will occur and the programmer can then resend the failed data transfer.  The normal use of this event is to set a global flag that indicates the network is ready.  When the SOCK_ERR_WOULDBLOCK occurs the flag is cleared.  Before sending data check the flag and if it is set the network can accept data.

See Also

Send


Connect

Description

Indicates a Connect action has successfully completed.

Syntax

Sub dsSocket_Connect ( [ Index As Integer] )

Remarks

The Connect event indicates that connection has been established in response to setting the Action property to SOCK_ACTION_CONNECT.  The control is now capable of sending and receiving data with a server process.

See Also

Action


Accept

Description

Indicates a socket with an active Listen has received a connect request from a client.

Syntax

Sub dsSocket_Accept ( [ Index As Integer, ] SocketID As Integer )

Remarks

In responding to this event the programmer must either create a new instance of the dsSocket control, or have created another instance at design-time, and assign the SocketID event parameter to the Socket property of the new control instance.  The new control instance then receives any communication events for this connection.  Upon successful completion of the setting of the Socket property the State property of the new instance of the control will be set to the value of SOCK_STATE_CONNECTED.

Example:

Sub dsSocket1_Accept( Index as Integer, SocketID as Integer )

Load dsSocket1(1)

dsSocket1(1).Socket = SocketID

End Sub

See Also

Action    Socket


Listen

Description

Indicates that a Listen has been established.

Syntax

Sub dsSocket_Listen ( [ Index As Integer ] )

Remarks

The Listen event indicates that a Listen has been established in response to setting the Action property to SOCK_ACTION_LISTEN.  The control is now capable of receiving incoming connections from a client process.

See Also

Action    LocalPort


Exception

Description

Indicates an error condition has occurred.

Syntax

Sub dsSocket_Exception ( [ Index As Integer, ] ErrorCode As Integer, ErrorDesc As String )

Remarks

The ErrorCode parameter provides the number of the error that occurred and the ErrorDesc provides a text description of the error.  Only asynchronous errors are provided with this event.  Errors occuring during the setting of properties are returned using the standard Visual Basic Err and Error variables.

See Also

Error Codes


LocalDotAddr

Description

Returns the IP address of the local computer.

Syntax

[form.]dsSocket1.LocalDotAddr

Remarks

Returns the IP address of the local computer in Internet dot notation (e.g.: 124.35.20.12).  Read only at run-time and design-time.

Data Type

String

See Also

LocalName


Linger

Description

Sets and returns the value of the Linger flag.

Syntax

[form.]dsSocket1.Linger [ = True | False ]

Remarks

The Linger flag determines the type of close utilized when the socket connection is closed.  It is used in conjunction with the Timeout property.  If the Linger property is set to True and the Timeout property is greater than 0 seconds, then setting the Action property to SOCK_ACTION_CLOSE will block until the socket is closed or the Timeout expires.  The default value is True.

Linger flag	Timeout	Type of close	Wait for close?

True	0	Hard	No

True	>0	Graceful	Yes

False	<any>	Graceful	No

Data Type

Boolean

See Also

Action    Timeout


Timeout

Description

Sets or returns the timeout for socket closing.

Syntax

[form.]dsSocket1.Timeout [ = setting% ]

Remarks

The Timeout property is utilized in conjuction with the Linger property to determine the type of close used when a socket connection is closed.  The value is specified in seconds.  If the Linger property is set to True then setting the Action property to SOCK_ACTION_CLOSE will block until the socket is closed or the Timeout expires.  The default value is 10 seconds.

Linger flag	Timeout	Type of close	Wait for close?

True	0	Hard	No

True	>0	Graceful	Yes

False	<any>	Graceful	No

Data Type

Integer

See Also

Action    Linger


State

Description

Sets and returns the current state of a socket control.

Syntax

[form.]dsSocket1.State [ = setting% ]

Remarks

The State property will reflect the known condition of the control.  If an Exception has occurred the State property will not change to reflect the error condition.  The programmer should determine if the error has disconnected the socket.  The property will be correctly set after an Action has been specified.

Data Type

Integer

See Also

Action    Exception


Socket

Description

Sets or returns the socket number to be used for communication.

Syntax

[form.]dsSocket1.Socket [ = setting% ]

Remarks

The Socket property is set in response to an Accept event.  It must be set to the value of the SocketID parameter provided in the Accept event.  The Socket property will be associated with a new instance of the control that is created when handling the Accept event.

Example:

Sub dsSocket1_Accept( Index As Integer, SocketID As Integer )

' create a new control to handle the incoming connection

Load dsSocket(1)

' set it to the specified socket number

dsSocket1.Socket = SocketID

' dsSocket1(1) will now be used to send and receive data

End Sub

Data Type

Integer

See Also

Accept


Close

Description

Indicates a socket connection has closed.

Syntax

Sub dsSocket_Close ( [ Index As Integer, ] ErrorCode As Integer, ErrorDesc As String )

Remarks

The Close event indicates that an active connection has been closed.  If the connection closed without errors then the ErrorCode will be 0 and the ErrorDesc will contain "Socket closed".  If an error occurred during the closing of the socket the ErrorCode parameter provides the number of the error that occurred and the ErrorDesc provides a text description of the error.

See Also

Error Codes