ST101 WinSock DLL

ST101WinSock.dll

This file describes ST101WinSock.dll. It contains a set of optimized socket routines that allow you to call the Winsock API directly from eMbedded Visual Basic and eMbedded Visual C++. These routines are meant to replace the WinSock ActiveX control that comes with eVB with the following advantages.

Improved performance by more than a factor of 10 over the WinSock ActiveX control.
Greater programming control, such as non-blocking functions.
The ability to handle binary data.
A simplified interface.

You can download the free personal version or purchase a commercial version of the software at http://www.SegueMD.com/winsock.

We can help you develop that wireless or socket-based application on your Pocket PC. We provide online training, technical support, and consulting for Windows CE, Palm OS, Internet Technologies, and the Oracle Relational Database.

If you need assistance with your Windows CE application, training, technical support, or consulting, please contact us at www.SegueMD.com.

Table of Contents

License
Installation
Winsock Programming Tips
Client Functions
Server Functions
Alphabetical List of Functions and Constants
Declarations for eVB
Declarations for eVC++

License

Personal Version

This program is provided "as is" with no implied or written warranty. Permission is granted to use this software for personal use only. Permission is granted to distribute to others for personal use as long as this document is included with the software, no fee is charged for this software, no handling or shipping fee is charged, and it is not bundled with any other item.

Commercial Version

A commercial version of the software, along with training courses for Windows CE, may be purchased at http://www.SegueMD.com/winsock. Software developed with the commercial version may be freely distributed, as long as the source code files with your software license (*.bas, *.frm, and *.cpp files) are not distributed.

Software License

The ST101_Connect() and ST101_Accept() functions must be called with a valid software license. For the personal version, use the text string "Personal" for the license.
The personal version displays a shareware message that must be dismissed each time a socket connection is made. This does not happen if you have a valid software license.

Installation

The software is compatible under Windows CE 3.0, and Pocket PC 2002 using the Palm-Sized PC, Handheld PC Pro, or Pocket PC. Select the correct DLL for your platform (MIPS, SH3, StrongArm, Emulator), and copy it to the \Windows directory on your Pocket PC.

Winsock Programming Tips

The purpose of this help file is to describe the functions provided. If you need help to learn how to program sockets under Windows CE, please check out the WinSock Programmer's FAQ. If you need additional help, we provide training, consulting, and programming support for an additional fee.

Binary Data Transfer

Because of the conversion between Visual Basic and Visual C++, all data is transferred in wide character strings. Look under ST101_Send and ST101_Recv for information on how to send and receive strings of binary data.

IP Address Resolution

The Pocket PC 2002 cannot resolve IP addresses unless the device is connected to a WINS server or has a host entry in its registry. This is not true for C/C++ programs under Windows CE 3.0, Windows 98, and Windows 2000. In addition, this is not true when using the WinSock Active X control under eVB. So as far as I can tell, this is a ~~bug~~ feature. It is documented at http://www.microsoft.com/mobile/pocketpc/tips/activesyncnet.asp. Microsoft recommends that you can download Pocket Hosts from Marc Zimmerman's site to create host entries in your registry.

Microsoft Pocket PC Connection Wizard

If your Pocket PC isn't configured for TCP/IP, you may need to download and run the Microsoft Pocket PC Connection Wizard. This wizard will run on your desktop and will help you set up your Pocket PC to accept a variety of connection options.

Client Functions

A simple client program would use the following functions.

ST101_WSAStartup
ST101_Socket
ST101_Connect
ST101_Send
ST101_Recv
ST101_DataWaiting
ST101_CloseSocket
ST101_WSACleanup

Public Sub SimpleClient()
    Dim iRet As Integer
    Dim buf As String
    Dim iSocket as Integer

    'Connect
    iRet = ST101_WSAStartup
    iSocket = ST101_Socket(AF_INET, SOCK_STREAM, 0)
    iRet = ST101_Connect(iSocket, "192.168.1.101", 23, "LICENSE")

    'Send data
    iRet = ST101_Send(iSocket, "Hello, world!", Len("Hello, world!"))

    'Read data, if any is waiting
    iRet = ST101_DataWaiting(iSocket)
    If iRet > 0 Then
        buf = Space(iRet)
        iRet = ST101_Recv(iSocket, buf, iRet)
    End If

    'Clean up
    iRet = ST101_closesocket(iSocket)
    iRet = ST101_WSACleanup()
End Sub

Server Functions

A simple server program would use the following functions.

ST101_WSAStartup
ST101_Socket
ST101_Bind
ST101_Listen
ST101_AcceptTimeOut
ST101_Send
ST101_Recv
ST101_DataWaiting
ST101_CloseSocket
ST101_ShutDown
ST101_WSACleanup

Public Sub SimpleServer()
    Dim iRet As Integer
    Dim localSocket, inputSocket As Integer
    Dim buf As String

    'Get into listening mode
    iRet = ST101_WSAStartup
    localSocket = ST101_Socket(AF_INET, SOCK_STREAM, 0)
    iRet = ST101_Bind(localSocket , 23)
    iRet = ST101_Listen(localSocket , 1, "LICENSE")

    'Make a connection
    inputSocket = ST101_AcceptTimeOut(iSocket, 20)
    If iRet < 0 Then Exit Sub

    'Send data
    iRet = ST101_Send(iSocket, "Hello, world!", Len("Hello, world!"))

    'Read data, if any is waiting
    iRet = ST101_DataWaiting(inputSocket)
    If iRet > 0 Then
        buf = Space(iRet)
        iRet = ST101_Recv(inputSocket, buf, iRet)
    End If

    'Clean up
    iRet = ST101_ShutDown(inputSocket)
    iRet = ST101_CloseSocket(inputSocket)
    iRet = ST101_CloseSocket(localSocket)
    iRet = ST101_WSACleanup()
End Sub

Alphabetical List of Functions and Constants

Constants
ST101_Accept
ST101_AcceptTimeOut
ST101_Bind
ST101_CloseSocket
ST101_Connect
ST101_ConnectTimeOut
ST101_DataWaiting
ST101_GetDLLVersion
ST101_GetHostName
ST101_GetHostNameFromIP
ST101_GetIPFromHostName
ST101_Listen
ST101_Recv
ST101_RecvTimeOut
ST101_Send
ST101_SendTimeOut
ST101_SetSockOpt_Tcp_NoDelay
ST101_Shutdown
ST101_Socket
ST101_WSACleanup
ST101_WSAGetLastError
ST101_WSAStartup

Constants

Note that these must be Private constants if they are declared in a form (*.ebf file). They may be Public constants if declared in a module (*.bas file).

Public Const AF_INET = 2
Public Const AF_IRDA = 22
Public Const SOCK_STREAM = 1
Public Const SOCK_DGRAM = 2
Public Const INVALID_SOCKET = -1
Public Const SOCKET_ERROR = -1

ST101_Accept

Description

This function accepts a connection on a socket.

Declaration

Declare Function ST101_Accept Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal license As String) As Integer

Arguments

Argument 1 is a socket that has been placed in a listening state.

Argument 2 is your ST101_WinSock.dll license. See the license section for more information.

Returns the socket on which the connection is being made, or INVALID_SOCKET on error.

ST101_AcceptTimeOut

Description

This function accepts a connection on a socket. It will timeout after a specified number of seconds.

Declaration

Declare Function ST101_AcceptTimeOut Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal sec As Integer, ByVal license As String) As Integer

Arguments

Argument 1 is a socket that has been placed in a listening state.

Argument 2 is the number of seconds to wait before timing out.

Argument 3 is your ST101_WinSock.dll license. See the license section for more information.

Returns the socket on which the connection is being made, or INVALID_SOCKET on error.

ST101_Bind

Description

This function associates a local address with a socket.

Declaration

Declare Function ST101_Bind Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal port As Integer) As Integer

Arguments

Argument 1 is an unbound socket.

Argument 2 is a local port.

Return value is zero, or INVALID_SOCKET on error.

ST101_CloseSocket

Description

This function closes a socket.

Declaration

Declare Function ST101_CloseSocket Lib "ST101WinSock.dll" (ByVal iSocket As Integer) As Integer

Arguments

Argument 1 is the socket to close.

Return value is zero, or SOCKET_ERROR on error.

ST101_Connect

Description

This function establishes a connection to a peer.

See the note under Winsock Programming Tips about IP address resolution.

Declaration

Declare Function ST101_Connect Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal addr As String, ByVal port As Integer, ByVal license As String) As Integer

Arguments

Argument 1 is an unconnected socket.

Argument 2 is a host name or IP address.

Argument 3 is a port number.

Argument 4 is your ST101_WinSock.dll license. See the license section for more information.

Return value is zero, or SOCKET_ERROR on error.

ST101_ConnectTimeOut

Description

This function establishes a connection to a peer. It will timeout after a specified number of seconds.

See the note under Winsock Programming Tips about IP address resolution.

Declaration

Declare Function ST101_ConnectTimeOut Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal addr As String, ByVal port As Integer, ByVal sec As Integer, ByVal license As String) As Integer

Arguments

Argument 1 is an unconnected socket.

Argument 2 is a host name or IP address.

Argument 3 is a port number.

Argument 4 is your ST101_WinSock.dll license. See the license section for more information.

Return value is zero, or SOCKET_ERROR on error.

ST101_DataWaiting

Description

This function determines if data is ready to be received by the specified socket.

Declaration

Declare Function ST101_DataWaiting Lib "ST101WinSock.dll" (ByVal iSocket As Integer) As Integer

Arguments

Argument 1 is the socket to check.

Return value is the number of characters waiting to be read.

ST101_GetDLLVersion

Description

This function returns the version of the ST101 DLL being used.

Declaration

Declare Function ST101_GetDLLVersion Lib "ST101WinSock.dll" () As String

Arguments

Return value is the version string of the DLL.

ST101_GetHostName

Description

This function returns the standard host name for the local computer.

Declaration

Declare Function ST101_GetHostName Lib "ST101WinSock.dll" () As String

Arguments

Return value is the host name, or an empty string on error.

ST101_GetHostNameFromIP

Description

This function retrieves the host name for a given IP address.

See the note under Winsock Programming Tips about IP address resolution.

Declaration

Declare Function ST101_GetHostNameFromIP Lib "ST101WinSock.dll" (ByVal addr As String) As String

Arguments

Argument is the IP address of the host in "192.168.1.1" format.

Return value is the host name, or an empty string on error.

ST101_GetIPFromHostName

Description

This function returns the IP address (in "192.168.1.1" format) for a given host name (in "mycomputer.com" format).

Declaration

Declare Function ST101_GetIPFromHostName Lib "ST101WinSock.dll" (ByVal addr As String) As String

Arguments

Argument 1 is the name of the host in "mycomputer.com" format.

Return value is the IP address, or an empty string on error.

ST101_Listen

Description

This function prepares a socket to listen for incoming connections.

Declaration

Declare Function ST101_Listen Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal backlog As Integer) As Integer

Arguments

Argument 1 is a bound, unconnected socket.

Argument 2 is the backlog value.

Return value is zero, or INVALID_SOCKET on error.

ST101_Recv

Description

This function receives data from a socket.

For binary data, use the Asc() function to remove bytes from the string of data received. For example ...
'binary_char and i are integers
iRet = ST101_Recv(iSocket, buf, buflen)
For i = 1 to iRet
binary_char = Asc(Mid(buf, i, 1))
'process the binary character
Next i

Declaration

Declare Function ST101_Recv Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal buf As String) As Integer

Arguments

Argument 1 is a connected socket.

Argument 2 is the buffer of data to that is received.

Argument 3 is the maximum number of characters that the buffer can hold.

Return value is the number of bytes received, or SOCKET_ERROR on error.

ST101_RecvTimeOut

Description

This function receives data from a socket. It will time-out after a specified number of seconds.

Declaration

Declare Function ST101_RecvTimeOut Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal buf As String, ByVal sec As Integer) As Integer

Arguments

Argument 1 is a connected socket.

Argument 2 is the buffer of data to that is received.

Argument 3 is the maximum number of characters that the buffer can hold.

Argument 4 is the number of seconds to wait before timing-out.

Return value is the number of bytes received, or SOCKET_ERROR on error.

ST101_Send

Description

This function sends data on a connected socket.

For binary data, use the Chr() function to create strings. For example ...
'Send 0x0008 as a string
ST101_Send(socket, Chr(0) + Chr(8), 2)

Declaration

Declare Function ST101_Send Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal buf As String, ByVal buflen As Integer) As Integer

Arguments

Argument 1 is a connected socket.

Argument 2 is the buffer of data to be sent.

Argument 3 is the length of the buffer of data to be sent.

Argument 3 is new in version 1.1

Return value is the number of bytes sent, or SOCKET_ERROR on error.

ST101_SendTimeOut

Description

This function sends data on a connected socket. It will time-out after a specified number of seconds.

Use the Chr() function to create strings of binary data. For example, ST101_Send(socket, Chr(0) + Chr(8), 2).

Declaration

Declare Function ST101_SendTimeOut Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal buf As String, ByVal buflen As Integer, ByVal sec As Integer) As Integer

Arguments

Argument 1 is a connected socket.

Argument 2 is the buffer of data to be sent.

Argument 3 is the length of the buffer of data to be sent.

Argument 3 is new in version 1.1

Argument 4 is the number of seconds to wait before timing-out.

Return value is the number of bytes sent, or SOCKET_ERROR on error.

ST101_SetSockOpt_Tcp_NoDelay

Description

This function disables the Nagle algorithm for send coalescing.

Declaration

Declare Function ST101_SetSockOpt_Tcp_NoDelay Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal opt As Integer) As Integer

Arguments

Return value is zero, or SOCKET_ERROR on error.

ST101_Shutdown

Description

This function disables send or receive operations on a socket. It does not release any system resources used by the socket.

Declaration

Declare Function ST101_Shutdown Lib "ST101WinSock.dll" (ByVal iSocket As Integer) As Integer

Arguments

Argument 1 is a socket.

Return value is zero, or INVALID_SOCKET on error.

ST101_Socket

Description

This function creates a socket.

Declaration

Declare Function ST101_Socket Lib "ST101WinSock.dll" (ByVal af As Integer, ByVal itype As Integer, ByVal protocol As Integer) As Integer

Arguments

Argument 1 is the address family specification. This should be set to AF_INET.

Argument 2 is the type for the new socket. This should be set to SOCK_STREAM.

Argument 3 is the protocol for the new socket. This should be set to zero.

Return value is new socket, or INVALID_SOCKET on error.

ST101_WSACleanup

Description

This function terminates the use of Winsock.dll.

Declaration

Declare Function ST101_WSACleanup Lib "ST101WinSock.dll" () As Integer

Arguments

Return values is zero, or SOCKET_ERROR on error.

ST101_WSAGetLastError

Description

This function retrieves the error status for the last Windows Socket operation that failed.

Declaration

Declare Function ST101_WSAGetLastError Lib "ST101WinSock.dll" () As Integer

Arguments

Return value is the error number of the last WinSock operation that failed on this thread.

ST101_WSAStartup

Description

This function initializes a WSADATA structure.

Declaration

Declare Function ST101_WSAStartup Lib "ST101WinSock.dll" () As Integer

Arguments

Return value is zero, or non-zero on error.

Declarations for eVB

To make it easier to use ST101WinSock with eVB, all declarations and constants are included below. Copy and paste this information into an eVB module (*.bas file).

Public Const AF_INET = 2
Public Const AF_IRDA = 22
Public Const SOCK_STREAM = 1
Public Const SOCK_DGRAM = 2
Public Const INVALID_SOCKET = -1
Public Const SOCKET_ERROR = -1

Declare Function ST101_Accept Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal license As String) As Integer
Declare Function ST101_AcceptTimeOut Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal sec As Integer, ByVal license As String) As Integer
Declare Function ST101_Bind Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal port As Integer) As Integer
Declare Function ST101_CloseSocket Lib "ST101WinSock.dll" (ByVal iSocket As Integer) As Integer
Declare Function ST101_Connect Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal addr As String, ByVal port As Integer, ByVal license As String) As Integer
Declare Function ST101_ConnectTimeOut Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal addr As String, ByVal port As Integer, ByVal sec As Integer, ByVal license As String) As Integer
Declare Function ST101_DataWaiting Lib "ST101WinSock.dll" (ByVal iSocket As Integer) As Integer
Declare Function ST101_GetDLLVersion Lib "ST101WinSock.dll" () As String
Declare Function ST101_GetHostName Lib "ST101WinSock.dll" () As String
Declare Function ST101_GetHostNameFromIP Lib "ST101WinSock.dll" (ByVal addr As String) As String
Declare Function ST101_GetIPFromHostName Lib "ST101WinSock.dll" (ByVal addr As String) As String
Declare Function ST101_Listen Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal backlog As Integer, ByVal license As String) As Integer
Declare Function ST101_Recv Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal buf As String, ByVal buflen As Integer) As Integer
Declare Function ST101_RecvTimeOut Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal buf As String, ByVal buflen As Integer, ByVal sec As Integer) As Integer
Declare Function ST101_Send Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal buf As String, ByVal buflen As Integer) As Integer
Declare Function ST101_SendTimeOut Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal buf As String, ByVal buflen As Integer, ByVal sec As Integer) As Integer
Declare Function ST101_SetSockOpt_Tcp_NoDelay Lib "ST101WinSock.dll" (ByVal iSocket As Integer, ByVal opt As Integer) As Integer
Declare Function ST101_Shutdown Lib "ST101WinSock.dll" (ByVal iSocket As Integer) As Integer
Declare Function ST101_Socket Lib "ST101WinSock.dll" (ByVal af As Integer, ByVal itype As Integer, ByVal protocol As Integer) As Integer
Declare Function ST101_WSACleanup Lib "ST101WinSock.dll" () As Integer
Declare Function ST101_WSAGetLastError Lib "ST101WinSock.dll" () As Integer
Declare Function ST101_WSAStartup Lib "ST101WinSock.dll" () As Integer

Declarations for eVC++

The ST101WinSock DLL can be called from an eVC++ program. The include file information for this purpose is shown below.

#define MYDLL_IMPLEMENTATION

#ifdef MYDLL_IMPLEMENTATION
#define DLLEXPORT _declspec(dllexport)
#else
#define DLLEXPORT _declspec(dllimport)
#endif

#ifdef __cplusplus
extern "C" {
#endif

DLLEXPORT int _cdecl ST101_WSAStartup (void);
DLLEXPORT int _cdecl ST101_WSACleanup (void);
DLLEXPORT SOCKET _cdecl ST101_Socket (int af, int itype, int protocol);
DLLEXPORT int _cdecl ST101_Connect (SOCKET s, TCHAR *host_address, int port_number, TCHAR *szLicense);
DLLEXPORT int _cdecl ST101_ConnectTimeOut (SOCKET s, TCHAR *host_address, int port_number, int timeOut, TCHAR *szLicense);
DLLEXPORT int _cdecl ST101_Bind (SOCKET s, int port_number);
DLLEXPORT int _cdecl ST101_Listen (SOCKET s, int backlog);
DLLEXPORT int _cdecl ST101_Accept (SOCKET s, TCHAR *szLicense);
DLLEXPORT int _cdecl ST101_AcceptTimeOut (SOCKET s, int timeOut, TCHAR *szLicense);

DLLEXPORT int _cdecl ST101_Send (SOCKET s, TCHAR *buf, int buflen);
DLLEXPORT int _cdecl ST101_SendTimeOut (SOCKET s, TCHAR *buf, int buflen, int timeOut);
DLLEXPORT int _cdecl ST101_Recv (SOCKET s, TCHAR *buf, int buflen);
DLLEXPORT int _cdecl ST101_RecvTimeOut (SOCKET s, TCHAR *buf, int buflen, int timeOut);
DLLEXPORT int _cdecl ST101_SetRecvTimeOut (SOCKET s, int timeOut);
DLLEXPORT int _cdecl ST101_SetSendTimeOut (SOCKET s, int timeOut);
DLLEXPORT int _cdecl ST101_CloseSocket (SOCKET s);
DLLEXPORT int _cdecl ST101_Shutdown (SOCKET s);
DLLEXPORT int _cdecl ST101_DataWaiting (SOCKET s);

DLLEXPORT int _cdecl ST101_SetSockOpt_Tcp_NoDelay (SOCKET s, int val);
DLLEXPORT int _cdecl ST101_SetSockOpt_Linger (SOCKET s, int val);
DLLEXPORT int _cdecl ST101_SetSockOpt_DontLinger (SOCKET s);
DLLEXPORT int _cdecl ST101_WSAGetLastError (void);
DLLEXPORT void _cdecl ST101_WSASetLastError (int val);
DLLEXPORT TCHAR * _cdecl ST101_GetHostNameFromIP (TCHAR *host_address);
DLLEXPORT TCHAR * _cdecl ST101_GetIPFromHostName (TCHAR *host_address);
DLLEXPORT TCHAR * _cdecl ST101_GetHostName (void);
DLLEXPORT TCHAR * _cdecl ST101_GetDLLVersion(void);

void checkLicense(TCHAR *szLicense);
void displayLicense(void);

#ifdef __cplusplus
}
#endif