VBSOCK - Help Contents

To learn how to use Help, press F1

Introduction
A description of VBSOCK. What it is, what you can do with it, and
when you would use it.

Visual Basic Declarations
Visual Basic Declarations required by VBSOCK. Paste
these straight into your own code.

List of Functions
Description and explanation of all the VBSOCK functions
available for use in your applications.

Error Messages and Codes
Comprehensive description of all error messages and codes
produced by VBSOCK.

VBSOCK Examples
Some examples and code snippets to make your use of
VBSOCK more efficient and enjoyable.

Product Support and Registration
This is a really important section. It tells you how to register your
copy of VBSOCK (please) and how to obtain product support.


VBSOCK - Introduction

What is VBSOCK?

VBSOCK is a DLL that can be used by Visual Basic programmers to reliably and easily perform network type communications programming. Even if you have never done any network programming, you will find VBSOCK simple to use as it provides a high degree of functionality with a minimum amount of fuss and overhead.

What files do I need to start network programming with VBSOCK?

Only one file is required, that is VBSOCK.DLL

What system requirements are there for VBSOCK to work?

VBSOCK requires a Winsock 1.1 compliant TCP/IP network subsystem. What this means in English is that a file called WINSOCK.DLL that conforms to version 1.1 of the Windows Sockets Specifications is located somewhere on your path. You don't really have to worry about this, VBSOCK will soon tell you if there is a problem.

What are Windows Sockets?

Clearly it is beyond the scope of this document to attempt to explain in detail the history and technical implementation of Windows Sockets. Here is a brief (really brief) explanation.

The Windows Sockets Specification is an independent specification which was created and exists for the benefit of application developers and network vendors. A socket is the basic building block for communications. It is an endpoint of communication which has a name. Think of sockets like tubes that connect one computer to another. Once a tube (read socket) has been established, network communication it is simply a matter of sending data down the tube and receiving data back up the tube.

If an application has been written that complies with version 1.1 of the Windows Sockets Specification it can be said to be Windows Sockets compliant and therefore should work with Winsock libraries from any vendor that adheres to the specification. Internally, VBSOCK uses only Winsock 1.1 function calls and is therefore Windows Sockets Compliant.

What sorts of things does VBSOCK allow the programmer to do?

VBSOCK lets you open sockets, close sockets, send data to sockets, receive data from sockets, make your PC a server and listen for connections to it, and more...

You can write programs which allows two people on your network to use their PC's to talk with each other.

You can get information from a UNIX host machine such as the time, the machines status, who is logged on, network printer queue status's, remote directory listings, remote file copies and so on.

You can turn your PC into a server that allows other people to logon to your PC.

Create your own TELNET applications.

Write network games. I am currently working on a network version of the card game 500.

Create a yellow notes popup message program to notify other users with messages and the like.

Get the picture, all sorts of network type tasks can be accomplished using VBSOCK.

See Also

VBSOCK - List of Functions

VBSOCK - Examples

Further Reference Material

Windows is a trademark of Microsoft Corporation.

UNIX is a trademark of Unix System Laboratories, Inc.

VAX is a trademark of Digital Equipment Corporation.

68000 is a trademark of Motorola, Inc.

NT and Windows/NT are trademarks of Microsoft Corporation


VBSOCK - Visual Basic Declarations

Listed below are all the Visual Basic declarations required by VBSOCK. Paste them straight into your code instead of retyping them. Even though you really only need to declare the functions of VBSOCK that your code actually uses, it is probably just as easy to paste them all in. Your code will then be ready for future enhancements.

Important Safety Tip - If you do not put VBSOCK.DLL in your path somewhere you will have to change the declarations below to specify exactly where the DLL is located.

Const SOCKERROR = -1

Const SOCKTIMEOUT = 0

Declare Function VBSOCKstartup% Lib "VBSOCK.DLL" ()

Declare Function VBSOCKopen% Lib "VBSOCK.DLL" (ByVal portNum%, ByVal hostName$)

Declare Function VBSOCKsend% Lib "VBSOCK.DLL" (ByVal sockNum%, ByVal buffer$, ByVal buflen%)

Declare Function VBSOCKrecv% Lib "VBSOCK.DLL" (ByVal sockNum%, ByVal buffer$, ByVal buflen%)

Declare Function VBSOCKpeek% Lib "VBSOCK.DLL" (ByVal sockNum%, ByVal timeout&)

Declare Function VBSOCKclose% Lib "VBSOCK.DLL" (ByVal sockNum%)

Declare Function VBSOCKcleanup% Lib "VBSOCK.DLL" ()

Declare Function VBSOCKserverStart% Lib "VBSOCK.DLL" (ByVal portNum%)

Declare Function VBSOCKserverStop% Lib "VBSOCK.DLL" ()

Declare Function VBSOCKgetLastError% Lib "VBSOCK.DLL" ()

Declare Function VBSOCKsetLastError% Lib "VBSOCK.DLL" (ByVal errorNum%)

Declare Function VBSOCKgetPortFromName% Lib "VBSOCK.DLL" (ByVal portName$)

Declare Function VBSOCKgetNameFromPort% Lib "VBSOCK.DLL" (ByVal portNum%, ByVal buffer$)

Declare Function VBSOCKsendKeepAlives% Lib "VBSOCK.DLL" (ByVal sockNum%, ByVal flag%)

Declare Function VBSOCKvendorInfo% Lib "VBSOCK.DLL" (ByVal buffer$)

Declare Function VBSOCKversionInfo% Lib "VBSOCK.DLL" (ByVal buffer$)

See Also

Error Code Constants

VBSOCK - List of Functions

VBSOCK - Examples


VBSOCK - List of Functions

Listed below are all the functions located in VBSOCK.DLL. Select the function that you require full information for...

VBSOCKstartup

VBSOCKopen

VBSOCKsend

VBSOCKrecv

VBSOCKpeek

VBSOCKclose

VBSOCKcleanup

VBSOCKserverStart

VBSOCKserverStop

VBSOCKsetLastError

VBSOCKgetLastError

VBSOCKgetPortFromName

VBSOCKgetNameFromPort

VBSOCKsendKeepAlives

VBSOCKvendorInfo

VBSOCKversionInfo

See Also

VBSOCK - Visual Basic Declarations

VBSOCK - Examples


 VBSOCK - Error Messages and Codes

How does VBSOCK handle error processing?

VBSOCK will always notify the application programmer if an error condition has occurred during any function call. The function that the error condition occurred in will normally return an error code of SOCKERROR. This error code is not very descriptive however, all it does is notify that an error has occurred.

To obtain a more detailed error message the function VBSOCKgetLastError should be used. The error conditions that this function can report are detailed below.

Error	Error Constant	Error Description
10000	WSAEOK	No error, normal operation
10004	WSAEINTR	Current blocking call cancelled
10014	WSAEFAULT	The buflen argument is incorrect.
10022	WSAEINVAL	The socket is not already bound to an address.
10024	WSAEMFILE	No more file descriptors are available.
10036	WSAEINPROGRESS	Indicates a VBSOCK operation is in progress.
10038	WSAENOTSOCK	The descriptor is not a socket.
10039	WSAEDESTADDREQ	A destination address is required.
10045	WSAEOPNOTSUPP	The referenced socket is not of a type that supports connection-oriented service.
10047	WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket
10048	WSAEADDRINUSE	The specified address is already in use
10049	WSAEADDRNOTAVAIL	The specified address is not available from the local machine.
10050	WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
10051	WSAENETUNREACH	The network can't be reached from this host at this time.
10052	WSAENETRESET	The connection must be reset because the Windows Sockets implementation dropped it.
10053	WSAECONNABORTED	The socket was aborted due to timeout or other failure.
10054	WSAECONNRESET	The socket was reset by the remote side.
10055	WSAENOBUFS	No buffer space is available. The socket cannot be created.
10056	WSAEISCONN	The socket is already connected.
10057	WSAENOTCONN	Connection has been reset due to keep-alive packets being sent.
10058	WSAESHUTDOWN	The socket has been shutdown. It is not possible to send or recv on this socket.
10060	WSAETIMEDOUT	Attempt to connect timed out without establishing a connection.
10061	WSAECONNREFUSED	The attempt to connect was forcefully rejected.
10091	WSASYSNOTREADY	Indicates that the network subsystem is unusable.
10092	WSAVERNOTSUPPORTED	Indicates that the Windows Sockets DLL cannot support this application.
10093	WSANOTINITIALISED	Indicates that a successful VBSOCKstartup has not yet been performed.
11001	WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
11002	WSATRY_AGAIN	Non-Authoritative Host not found
11003	WSANO_RECOVERY	Indicates a non recoverable error has occurred.
11004	WSANO_DATA	Valid name, no data record of requested type.

See Also

SOCKERROR

SOCKTIMEOUT

Error Code Constants

VBSOCKgetLastError - Syntax and Usage

VBSOCKsetLastError - Syntax and Usage


VBSOCK - Examples

What I have chosen to do with the Visual Basic examples is include them in this help file rather than include them as extra project files and so on. It is pretty easy to copy and paste the example code in this file straight into your VB application if you wish. At least this way there aren't as many files and directories to worry about keeping track of, just the one VBSOCK.HLP file.

Example Code

Just The Basics

Get The Time

Complete Function Test

Bits and Pieces


VBSOCK - Product Support and Registration

Limitation of liability:

VBSOCK IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL, BUT WITHOUT ANY WARRANTY; WITHOUT EVEN THE IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. GOOD DATA PROCESSING PROCEDURE DICTATES THAT ANY PROGRAM BE THOROUGHLY TESTED WITH NON-CRITICAL DATA BEFORE RELYING ON IT. THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM. NEITHER AUTHOR NOR ANY OTHER PARTIES INVOLVED SHALL BE HELD LIABLE FOR ANY KIND OF DAMAGES OR CLAIMS THAT DIRECTLY OR INDIRECTLY RESULT FROM USING THIS SOFTWARE.

BY USING THE SHAREWARE VERSION OF VBSOCK.DLL YOU ACKNOWLEDGE THAT YOU HAVE READ THIS LIMITED WARRANTY, UNDERSTAND IT, AND AGREE TO BE BOUND BY ITS' TERMS AND CONDITIONS. YOU ALSO AGREE THAT THE LIMITED WARRANTY IS THE COMPLETE AND EXCLUSIVE STATEMENT OF AGREEMENT BETWEEN THE PARTIES AND SUPERSEDE ALL PROPOSALS OR PRIOR AGREEMENTS, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS BETWEEN THE PARTIES RELATING TO THE SUBJECT MATTER OF THE LIMITED WARRANTY.

Stuff

Well, this is the part where I try to make you feel guilty and pay me some money. I have actually put quite a bit of work into this product, and by doing so I hope to have made sockets programming available to VB programmers who would not normally be writing network and socket based applications.

You will have noticed (if you have used the library yet) that a message box pops up when you call VBSOCKstartup asking you to register. Apart from this annoyance, the version of VBSOCK that you have at the moment is in no way crippled or deficient All the functions it contains are fully operational.

VBSOCK is packaged as a DLL rather than a VBX . In my opinion I feel there is a little more functionality in a DLL than in a VBX. I may be wrong though and I am sure people will soon let me know if I am. If you prefer the VBX style of library, there are many good products available that are packaged as VBX's.

As this is a version 1.0 product I would be most interested in receiving comments, suggestions, criticisms and opinions as to how this product functions and how it could be improved. Send me a note or email me on the internet at jh040@seqeb.gov.au.

I would expect the next version of VBSOCK to be MUCH more expensive than this one, So now is your chance to get a cheap copy.

Why Register?

1.	When you register this product you will receive a version of VBSOCK without the nag screen.

2.	Your version will show YOUR name when VBSOCKversionInfo is called.

3.	You will receive any minor upgrades and bug fixes free of charge.

4.	You will get a significant discount on any major upgrades.

5.	You will receive a VBSOCK.HLP file with more examples and fewer spelling mistaks.

6.	You will receive product support.

7.	You will make me very happy.

8.	You will be able to sleep at night knowing that you have done the right thing.

9.	etc etc etc etc

How Much and How?

The registration fee for VBSOCK.DLL is $20.00 Australian. Payments can made by cheque or money order. Print the Registration form and mail your cheque or money order with the registration form to:-

John Michael Hnidec

10 Anita St.

Yeronga  4104

Brisbane, QLD

Australia

Please also include $5.00 for shipping and postage.

Registration Form


VBSOCKstartup - Syntax and Usage

Purpose:

Initialises the Windows sockets sub system.

Remarks:

This function MUST be the first VBSOCK function called by your application. The return value should always be checked to ensure a successful startup has occurred. For every call to this function a corresponding call to VBSOCKcleanup needs to be performed. Once your application has made a successful VBSOCKstartup call, it may proceed to make other VBSOCK function calls as required.

IMPORTANT - Unlike every other VBSOCK function, this function will NOT return SOCKERROR on error, it will actually return the error code itself. What this means is that the function call VBSOCKgetLastError cannot be reliably used to obtain error information returned by VBSOCKstartup. The reason is this function, among other things, initialises the area where the last error information is stored. If this initialisation fails, any results returned from VBSOCKgetLastError will be meaningless.

Declaration:

Declare Function VBSOCKstartup% Lib "VBSOCK.DLL" ()

Parameters:

None

Return Value:

0 on success

10091 WSASYSNOTREADY

Indicates that the underlying network subsystem is not ready for network communication.

10092 WSAVERNOTSUPPORTED

The version of Windows Sockets API support requested is not provided by this particular Windows Sockets implementation.

10022 WSAEINVAL

The Windows Sockets version specified by the application is not supported by this DLL.

See Also:

VBSOCKcleanup - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKopen - Syntax and Usage

Purpose:

Creates a socket for future sending and receiving of data.

Remarks:

This function MUST be called to enable the use of sockets for sending and receiving of data to a specified host. It returns a socket handle which is used as a parameter in many other VBSOCK function calls.

Declaration:

Declare Function VBSOCKopen% Lib "VBSOCK.DLL" (ByVal portNum%, ByVal hostName$)

Parameters:

portNum	An integer representing the port number you wish to connect to.

hostName	A string representing the name of the host you wish to connect to.

Return Value:

A socket number > 0 on success

SOCKERROR on error

See Also:

VBSOCKclose - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKsend - Syntax and Usage

Purpose:

Sends data to a previously opened socket.

Remarks:

This function sends data to a socket previously opened with VBSOCKopen. A successful call to VBSOCKopen must have occurred before data can be sent using this function. It returns the number of bytes sent on success which would normally be the same as the parameter buflen.

Declaration:

Declare Function VBSOCKsend% Lib "VBSOCK.DLL" (ByVal sockNum%, ByVal buffer$, ByVal buflen%)

Parameters:

sockNum	An integer representing a previously opened socket.

buffer	A string representing the data you wish to send.

buflen	An integer representing the length of buffer.

Return Value:

The number of bytes sent on success

SOCKERROR on error

See Also:

VBSOCKrecv - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKrecv - Syntax and Usage

Purpose:

Receives data from a previously opened socket.

Remarks:

This function receives data from  a socket previously opened with VBSOCKopen. A successful call to VBSOCKopen must have occurred before data can be received using this function. If this function is called and no data is waiting to be read, it will return 0 as the number of bytes read. VBSOCKpeek can be used to check if any data is waiting to be read. VBSOCKrecv will read either as many characters as is waiting to be read or up to the length of buffer.

Declaration:

Declare Function VBSOCKrecv% Lib "VBSOCK.DLL" (ByVal sockNum%, ByVal buffer$, ByVal buflen%)

Parameters:

sockNum	An integer representing a previously opened socket.

buffer	A string representing the location to store data received.

buflen	An integer representing the length of buffer.

Return Value:

The number of bytes read on success

SOCKERROR on error

See Also:

VBSOCKsend - Syntax and Usage

VBSOCKpeek - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKpeek - Syntax and Usage

Purpose:

Checks to see if any data is waiting to be read from a previously opened socket.

Remarks:

This function waits for a specified period of time for data to become available for reading. It will return as soon as data is available for reading or will wait for the specified amount of time. If no data is available for reading after the time specified it will return with SOCKTIMEOUT.

Declaration:

Declare Function VBSOCKpeek% Lib "VBSOCK.DLL" (ByVal sockNum%, ByVal timeout&)

Parameters:

sockNum	An integer representing a previously opened socket.

timeout	A long integer representing the timeout period in seconds.

Return Value:

The number of characters waiting to be read

SOCKTIMEOUT if no data waiting after specified time period

SOCKERROR on error

See Also:

VBSOCKrecv - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKclose - Syntax and Usage

Purpose:

Closes a previously opened socket and frees any resources allocated to that socket.

Remarks:

This function should be called once for every successful call to VBSOCKopen. Only a certain amount of buffer space is available for the use of sockets. Although this varies from vendor to vendor, a socket that is no longer required for use should be closed and any resources that socket is using made available to the system. VBSOCKclose ensures that will happen.

Declaration:

Declare Function VBSOCKclose% Lib "VBSOCK.DLL" (ByVal sockNum%)

Parameters:

sockNum	An integer representing a previously opened socket.

Return Value:

0 on success

SOCKERROR on error

See Also:

VBSOCKopen - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKcleanup - Syntax and Usage

Purpose:

Closes the socket subsystem.

Remarks:

This function MUST be called once for every successful call to VBSOCKstartup. Normally VBSOCKstartup would be called at the beginning of your application and VBSOCKcleanup called at the end of your application. Normally only one call to each function would be made per application but can vary depending on programming style and requirements.

Declaration:

Declare Function VBSOCKcleanup% Lib "VBSOCK.DLL" ()

Parameters:

None

Return Value:

0 on success

SOCKERROR on error

See Also:

VBSOCKstartup - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKserverStart - Syntax and Usage

Purpose:

Places the PC in server mode allowing it to listen for incoming connections.

Remarks:

This function allows the PC to act as a server and accept connections from other hosts. A successful call to VBSOCKstartup must occur before this function can be used. This function will continue to listen for incoming connections until one is received or until it is cancelled by VBSOCKserverStop. Once a successful connection has been established, the usual VBSOCK functions like VBSOCKsend and VBSOCKrecv can be used with the newly created socket.

Declaration:

Declare Function VBSOCKserverStart% Lib "VBSOCK.DLL" (ByVal portNum%)

Parameters:

portNum	An integer representing the port number to listen for connections on.

Return Value:

A socket number > 0 on success

SOCKERROR on error

See Also:

VBSOCKserverStop - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKserverStop - Syntax and Usage

Purpose:

Stops the PC from listening for incoming connections from other hosts.

Remarks:

This function takes the PC out of server mode and prevents any other connections to it being made. Once the function call VBSOCKserverStart has been made, the PC will stay in server mode until an incoming connection has been established or until VBSOCKserverStop has been called.

Declaration:

Declare Function VBSOCKserverStop% Lib "VBSOCK.DLL" ()

Parameters:

None

Return Value:

0 on success

SOCKERROR on error

See Also:

VBSOCKserverStart - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKgetLastError - Syntax and Usage

Purpose:

Retrieves detailed error information based on the last error that occurred.

Remarks:

Whenever a VBSOCK function fails with an error it returns SOCKERROR. For a more detailed and meaningful error report use VBSOCKgetLastError as soon as a function call has failed. This function will return an error number based on the standard Berkley sockets definition of standard errors. See Error Messages and Codes for a complete description of all possible errors.

Please Note -This function CANNOT be used reliably to retrieve error information based on a failed VBSOCKstartup function call since the Windows sockets DLL may not have established the client data error where the "last error" information is stored.

Declaration:

Declare Function VBSOCKgetLastError% Lib "VBSOCK.DLL" ()

Parameters:

None

Return Value:

An integer representing the last error that occurred.

See Also:

VBSOCKsetLastError - Syntax and Usage

Error Messages and Codes

VBSOCK - Visual Basic Declarations


VBSOCKsetLastError - Syntax and Usage

Purpose:

Sets the error code which can be retrieved by VBSOCKgetLastError

Remarks:

This function would mainly be used for debugging and testing of applications to ensure they can handle all appropriate error conditions.

Declaration:

Declare Function VBSOCKsetLastError% Lib "VBSOCK.DLL" (ByVal errorNum%)

Parameters:

errorNum	An integer representing the error code to be returned by VBSOCKgetLastError.

Return Value:

Always 0

See Also:

VBSOCKgetLastError - Syntax and Usage

Error Messages and Codes

VBSOCK - Visual Basic Declarations


VBSOCKvendorInfo - Syntax and Usage

Purpose:

Provides a method of retrieving the Windows sockets vendor information of your systems socket implementation.

Remarks:

This function retrieves the vendor information of your Windows socket implementation. The text retrieved will be a maximum of 256 characters in length and can be in any format the vendor wishes. It is generally accepted that the text will not contain any control and formatting characters, only printable ASCII text. This information is generally used in displays or status messages.

Declaration:

Declare Function VBSOCKvendorInfo% Lib "VBSOCK.DLL" (ByVal buffer$)

Parameters:

buffer	A string representing the location to store the vendor information.

Return Value:

0 on success

SOCKERROR on error

See Also:

VBSOCKversionInfo - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKversionInfo - Syntax and Usage

Purpose:

Provides a method of retrieving the version information contained in VBSOCK.DLL

Remarks:

This function retrieves the current version of VBSOCK. It is guaranteed the string retrieved will be in the format "9.9.9 dd/mm/yyyy REGISTRATION DETAILS", where 9.9.9 is the version number, dd/mm/yyyy is the version date, and the remainder of the string is the registered name of the owner of VBSOCK. This function may be useful in future releases where new features are available in some versions and not others. The maximum length of the string returned will not exceed 128 characters.

Declaration:

Declare Function VBSOCKversionInfo% Lib "VBSOCK.DLL" (ByVal buffer$)

Parameters:

buffer	A string representing the location to store the version information.

Return Value:

0 on success

SOCKERROR on error

See Also:

VBSOCKvendorInfo - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


SOCKERROR

A constant defined to be -1. This is the standard error
code returned by most VBSOCK functions.


SOCKET

A connection between two computers enabling
the bi-directional transfer of data between them
using the Berkley "socket" paradigm.


SOCKTIMEOUT

A constant defined to be 0. This warning is returned only
from the function VBSOCKpeek.


SERVER

Terminology used to describe the process of
one computer servicing one or more other
computers with requested information and
services. Computers connected to a server are
commonly called client computers. Hence the
Client/Server concept.


VBSOCK - Error Code Constants

Listed below are the Error Constants which can be pasted into your VB code if required.

Global Const WSAEOK = 10000

Global Const WSAEINTR = 10004

Global Const WSAEFAULT = 10014

Global Const WSAEINVAL = 10022

Global Const WSAEMFILE = 10024

Global Const WSAEINPROGRESS = 10036

Global Const WSAENOTSOCK = 10038

Global Const WSAEDESTADDREQ = 10039

Global Const WSAEOPNOTSUPP = 10045

Global Const WSAEAFNOSUPPORT = 10047

Global Const WSAEADDRINUSE = 10048

Global Const WSAEADDRNOTAV = 10049

Global Const WSAENETDOWN = 10050

Global Const WSAENETUNREACH = 10051

Global Const WSAENETRESET = 10052

Global Const WSAECONNABORTED = 10053

Global Const WSAECONNRESET = 10054

Global Const WSAENOBUFS = 10055

Global Const WSAEISCONN = 10056

Global Const WSANOTCONN = 10057

Global Const WSAESHUTDOWN = 10058

Global Const WSAETIMEDOUT = 10060

Global Const WSAECONNREFUSED = 10061

Global Const WSASYSNOTREADY = 10091

Global Const WSAVERNOTSUPPORTED = 10092

Global Const WSANOTINITIALISED = 10093

Global Const WSAHOST_NOT_FOUND = 11001

Global Const WSATRY_AGAIN = 11002

Global Const WSANO_RECOVERY = 11003

Global Const WSANO_DATA = 11004

See Also

SOCKERROR

SOCKTIMEOUT

Error Messages and Codes

VBSOCK - Visual Basic Declarations

VBSOCKgetLastError - Syntax and Usage

VBSOCKsetLastError - Syntax and Usage


VBSOCK - Further Reference Material

If you are the sort who likes to know lots of technical information about how something works or if you are interested in Sockets programming, the following references may be helpful:

Braden, R. [1989], RFC1122, Requirements for Internet Hosts--Communication Layers, Internet Engineering Task Force.

Comer, D. [1991], Internetworking with TCP/IP Volume I: Principles, Protocols, and Architecture, Prentice Hall, Englewood Cliffs, New Jersey.

Comer, D. and Stevens, D. [1991], Internetworking with TCP/IP Volume II: Design, Implementation, and Internals, Prentice Hall, Englewood Cliffs, New Jersey.

Comer, D. and Stevens, D. [1991], Internetworking with TCP/IP Volume III: Client-Server Programming and Applications, Prentice Hall, Englewood Cliffs, New Jersey.

Leffler, S. er al., An Advanced 4.3BSD Interprocess Communication Tutorial.

Petzold, C. [1992], Programming Windows 3.1, Microsoft Press, Redmond, Washington.

Stevens, W.R [1990], Unix Network Programming, Prentice Hall, Englewood Cliffs, New Jersey.


VBSOCKsendKeepAlives - Syntax and Usage

Purpose:

Enables or disables the sending of keep-alive packets to a connected socket.

Remarks:

Keep-alives are small packets of data which can be sent to a TCP socket connection which can prevent time outs from occurring. It is important to note that a Windows Sockets implementation need not support the use of keep-alives; if it does, the precise semantics are implementation-specific but should conform to 4.2.3.6 of RFC 1122. If your systems socket implementation does not support keep-alive packets, the call to this function will fail with SOCKERROR and the call to VBSOCKgetLastError will return error code 10052 WSAENETRESET.

Declaration:

Declare Function VBSOCKsendKeepAlives% Lib "VBSOCK.DLL" (ByVal sockNum%, ByVal flag%)

Parameters:

sockNum	An integer representing a previously opened socket.

flag	Either True to send keep-alive packets or False to stop sending keep-alive packets.

Return Value:

0 on success

SOCKERROR on error

See Also:

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKgetPortFromName - Syntax and Usage

Purpose:

Gets the port number of a particular service name.

Remarks:

This function is used to retrieve the port number of a given service name from a remote host. For example if you passed the parameter "telnet" to this function it would probably return 23 because the well known port number for the service "telnet" is 23.

Declaration:

Declare Function VBSOCKgetPortFromName% Lib "VBSOCK.DLL" (ByVal buffer$)

Parameters:

buffer	A string representing a service name.

Return Value:

port number > 0 on success

SOCKERROR on error

See Also:

VBSOCKgetNameFromPort - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


VBSOCKgetNameFromPort - Syntax and Usage

Purpose:

Gets the service name of a particular port number

Remarks:

This function is used to retrieve the service name of a given port number from a remote host. For example if you passed the parameter 23 to this function it would probably return "telnet" because the well known service name for port number 23 is "telnet".

Declaration:

Declare Function VBSOCKgetNameFromPort% Lib "VBSOCK.DLL" (ByVal portNum%, ByVal buffer$)

Parameters:

portNum	An integer representing a port number to query.

buffer	A string to store the service name of the requested port number.

Return Value:

0 on success and service name in buffer

SOCKERROR on error

See Also:

VBSOCKgetPortFromName - Syntax and Usage

VBSOCK - Examples

VBSOCK - List of Functions

VBSOCK - Visual Basic Declarations


Just The Basics

Notes:

A couple of important things to be aware of here. Firstly, any string variables that are passed to VBSOCK functions must be either declared as a fixed length variable or set to a fixed length later on in your code. Failure to do this will result in all sorts of horrible things happening such as GPF errors and the like.

Dim buffer As String * 128	GOOD

Dim buffer As String	GOOD

buffer = Space$(128)

Dim buffer As String	BAD

Another thing to be aware of is the VBSOCK function call VBSOCKgetLastError is only valid until the next VBSOCK function call.

Dim i As Integer

Dim info1 As String * 256

Dim info2 As String * 256

i = VBSOCKstartup()

If i <> 0 Then

MsgBox "Unable to Initialise the sockets subsystem"

Exit Sub

End If

i = VBSOCKvendorInfo(info1)

MsgBox "Sockets Vendor Information is - " & info1

i = VBSOCKversionInfo(info2)

MsgBox "VBSOCK Version Information is - " & info2

i = VBSOCKgetLastError()

MsgBox "Last Error code From VBSOCK was " & Str$(i)

i = VBSOCKcleanup()

MsgBox "Return code form VBSOCKcleanup was " & Str$(i)


Get The Time

Notes:

On most UNIX hosts, their is a service that returns the time on port 13. This example connects to port 13 of a host called "myserver", you will have to change this name to one of your own host names. It then waits for a maximum of 10 seconds for a reply from the host and displays the data received or a timeout error.

Also note that for every successful call to VBSOCKopen we have a call to VBSOCKclose and for every successful call to VBSOCKstartup we have a call to VBSOCKcleanup, even if an error condition occurs.

Dim i As Integer

Dim sock As Integer

Dim buffer As String * 128

i = VBSOCKstartup()

If i <> 0 Then

MsgBox "Unable to initialise"

Exit Sub

End If

sock = VBSOCKopen(13, "myserver")

If sock = SOCKERROR Then

i = VBSOCKcleanup()

MsgBox "Unable to open socket"

Exit Sub

End If

i = VBSOCKpeek(sock, 10)

If i = SOCKTIMEOUT Then

i = VBSOCKclose(sock)

i = VBSOCKcleanup()

MsgBox "Unable to connect to time service"

Exit Sub

End If

i = VBSOCKrecv(sock, buffer, Len(buffer))

MsgBox buffer

i = VBSOCKclose(sock)

i = VBSOCKcleanup()


Bits and Pieces

The general flow of things:

The general order of socket programming is usually to

Initialise the sockets library ( VBSOCKstartup )

Open a socket to another host computer ( VBSOCKopen )

Start sending and receiving data on that open socket ( VBSOCKsend or VBSOCKrecv )

Close the socket when network communication is complete ( VBSOCKclose )

Cleanup the sockets library ( VBSOCKcleanup )

How to continually read incoming data:

Possibly the best way is to put some code like this in a timer event.

Dim i As Integer

Dim temp As String * 4096

i = VBSOCKpeek(sock, 0)

If i > 0 then

i = VBSOCKrecv(sock, temp, Len(temp))

globalBuffer = globalBuffer & Left$(temp, i)

End If

How to continually read data until a certain character or string is returned:

this will read all incoming data into the variable incomingData until the # character appears

j = True

While j = True

i = VBSOCKpeek(sock, 10)

If i <> 0 Then

MsgBox "Timeout while reading"

i = VBSOCKclose(sock)

Exit Sub

End If

buffer = ""

i = VBSOCKrecv(sock, buffer, Len(buffer))

incomingData = incomingData & Left$(buffer, i)

If InStr(1, incomingData, "#") <> 0 Then j = False

Wend

How to set up the pc as a server:

This bit of code will put your pc into server mode.

Dim i As Integer

i = VBSOCKstartup()

i = VBSOCKserverStart(3000)

' the pc is now waiting for incoming connections on port 3000

' the next line of code will not execute until a connection

' is made or until a call to VBSOCKserverStop is made.

If i > 0 then

MsgBox "A successful connection has been made"

Else

MsgBox "Connection cancelled"

End If


Registration Form

Registration for VBSOCK.DLL

Please send me a registered version of VBSOCK. I have enclosed a cheque or money order for $25.00 made payable to John Hnidec This includes $20.00 for VBSOCK and $5.00 for postage and handling.

Registration Name

Please register VBSOCK using the following name. The name specified here will appear as details returned by the function call to VBSOCKversionInfo

____________________________________

Postage Details

Please send my copy of VBSOCK to the following address.

Name:	____________________________________________________

Street:	____________________________________________________

City:	____________________________________________________

State: 	____________________________________________________

country:	____________________________________________________

Post/Zip Code:	____________________________________________________

Media Type

3.5" Floppy Diskette

or

5.25" Floppy Diskette

Thankyou for registering VBSOCK. The author appreciates your effort and wishes you every success in the world of programming.


Complete Function Test

Notes:

This snippet of code will call every VBSOCK function apart from VBSOCKserverStart and VBSOCKserverStop. It will pop up a msgbox with the return value from each call. Use this for example syntax as well as testing your system to see if it is configured correctly for socket based programming.

Dim i As Integer

Dim sock As Integer

Dim buffer As String * 128

i = VBSOCKstartup()

MsgBox "VBSOCKstartup returned " & Str$(i)

buffer = Space$(128)

i = VBSOCKversionInfo(buffer)

MsgBox "VBSOCKversionInfo returned " & buffer

buffer = Space$(128)

i = VBSOCKvendorInfo(buffer)

MsgBox "VBSOCKvendorInfo returned " & buffer

sock = VBSOCKopen(23, "hostname")

MsgBox "VBSOCKopen returned " & Str$(sock)

i = VBSOCKsend(sock, "test", 4)

MsgBox "VBSOCKsend returned " & Str$(i)

i = VBSOCKpeek(sock, 2)

MsgBox "VBSOCKpeek returned " & Str$(i)

i = VBSOCKrecv(sock, buffer, Len(buffer))

MsgBox "VBSOCKrecv returned " & Str$(i)

i = VBSOCKsendKeepAlives(sock, True)

MsgBox "VBSOCKsendKeepAlives returned " & Str$(i)

i = VBSOCKsendKeepAlives(sock, False)

MsgBox "VBSOCKsendKeepAlives returned " & Str$(i)

i = VBSOCKsetLastError(12345)

MsgBox "VBSOCKsetLastError returned " & Str$(i)

i = VBSOCKgetLastError()

MsgBox "VBSOCKgetLastError returned " & Str$(i)

i = VBSOCKgetPortFromName("telnet")

MsgBox "VBSOCKgetPortFromName returned " & Str$(i)

buffer = Space$(128)

i = VBSOCKgetNameFromPort(23, buffer)

MsgBox "VBSOCKgetNameFromPort returned " & buffer

i = VBSOCKclose(sock)

MsgBox "VBSOCKclose returned " & Str$(i)

i = VBSOCKcleanup()

MsgBox "VBSOCKcleanup returned " & Str$(i)