S/Ocket

S/Ocket

Sprezzatura's S/Ocket is a 32-bit DLL that enables a developer to include basic TCP/IP communications to a server from their 32-bit OpenInsight application/s and ARev and OI16-bit applications using an OI32 runtime.

Whereas the socket functionality in OpenInsight 7.1 is designed to handle high-level protocols such as FTP and HTTP, S/ocket is designed to provide more flexibility to the developer by allowing 'raw' data streams to be sent and received, thus granting the ability to implement custom and extended TCP protocol programming.

There are 8 functions that have been prototyped in OpenInsight and each is highlighted below to give you an idea of what can be achieved using S/Ocket.

	zzx_TCPConnect
	zzx_TCPClose
	zzx_TCPWrite
	zzx_TCPWriteLn
	zzx_TCPRead
	zzx_TCPReadLn
	zzx_TCPReadEx
	zzx_TCPReadLnEx

Definitions

zzx_TCPConnect

This function makes a connection to a server on a specified port and must be called before any further communications with the server can take place.

retVal = zzx_TCPConnect( lpDestination, lpPort )

Arguments

lpDestination	This is a null terminated string that specifies the host name (eg. 'www.sprezzatura.com') or IP Address (eg. '127.0.0.1' ) to connect to.
iPort	This is the number of the port to connect to on the host.

Returns

If the function is successful a handle to the connection is returned (this must be used in subsequent communications with the server). If the function fails for any reason then 0 is returned.

Example

declare function zzx_TCPConnect

lpDest = 'www.sprezzatura.com' : \00\
iPort = 80

hSocket = zzx_TCPConnect( lpDest, iPort )

[Top]

zzx_TCPClose

This subroutine is used to close the connection to a server previously opened with the zzx_TCPConnect() function.

call zzx_TCPClose( hSocket )

Arguments:

hSocket

Handle to an open connection ( ie the value returned from zzx_TCPConnect ).

Returns

N/A

Example

declare function zzx_TCPConnect
declare subroutine zzx_TCPClose

lpDest = 'www.sprezzatura.com' : \00\
iPort = 80

hSocket = zzx_TCPConnect( lpDest, iPort )

   if hSocket then
      * // Do some comms stuff....
      call zzx_TCPClose( hSocket )

end

[Top]

zzx_TCPWrite

This function is used to send data to a server.

retVal = zzx_TCPWrite( hSocket, lpBuffer, iBufferLen )

Arguments:

hSocket	Handle to an open connection (ie the value returned from zzx_TCPConnect ).
lpBuffer	Variable containing the data to write.
iBufferLen	Number of bytes contained in lpBuffer. If this value is less than 0 then lpBuffer is assumed to be a null-terminated string and it's length calculated accordingly.

Returns

Returns 1 if successful, 0 otherwise.

Example

declare function zzx_TCPConnect, zzx_TCPWrite
declare subroutine zzx_TCPClose

lpDest = 'www.sprezzatura.com' : \00\
iPort = 80

hSocket = zzx_TCPConnect( lpDest, iPort )

   if hSocket then
      * // send some data to the server
      lpBuffer   = 'Some data to send' : \00\
      iBufferLen = len( lpBuffer ) - 1

retVal = zzx_TCPWrite( hSocket, lpBuffer, iBufferLen )

* // More processing ....

call zzx_TCPClose( hSocket )

end

[Top]

zzx_TCPWriteLn

This function is used to send data to a server but an EOL string is appended to the data before it is sent (ie... Char(13) and Char(10))

retVal = zzx_TCPWriteLn( hSocket, lpBuffer, iBufferLen )

Arguments:

hSocket	Handle to an open connection (ie the value returned from zzx_TCPConnect ).
lpBuffer	Variable containing the data to write.
iBufferLen	Number of bytes contained in lpBuffer. If this value is less than 0 then lpBuffer is assumed to be a null-terminated string and it's length calculated accordingly.

Returns

Returns 1 if successful, 0 otherwise.

Example

declare function zzx_TCPConnect, zzx_TCPWriteLn
declare subroutine zzx_TCPClose

lpDest = 'www.sprezzatura.com' : \00\
iPort = 80

hSocket = zzx_TCPConnect( lpDest, iPort )

   if hSocket then
      * // send some data to the server
      lpBuffer   = 'Some data to send' : \00\
      iBufferLen = len( lpBuffer ) - 1

retVal = zzx_TCPWriteLn( hSocket, lpBuffer, iBufferLen )

* // More processing ....

call zzx_TCPClose( hSocket )

end

[Top]

zzx_TCPRead

This function is used to read data from a server.

retVal = zzx_TCPRead( hSocket, lpBuffer, iBufferLen )

Arguments:

hSocket	Handle to an open connection (ie the value returned from zzx_TCPConnect ).
lpBuffer	Variable to read the data from the server into.
iBufferLen	Number of bytes contained in lpBuffer.

Returns

Returns 1 if successful, 0 otherwise.

Example

declare function zzx_TCPConnect, zzx_TCPWrite, zzx_TCPRead
declare subroutine zzx_TCPClose

lpDest = 'www.sprezzatura.com' : \00\
iPort = 80

hSocket = zzx_TCPConnect( lpDest, iPort )

   if hSocket then
      * // send some data to the server
      lpBuffer   = 'Some data to send' : \00\
      iBufferLen = len( lpBuffer ) - 1

retVal = zzx_TCPWrite( hSocket, lpBuffer, iBufferLen )

      if retVal then
         * // Get some data from the server
         lpBuffer   = str( \00\, 2048 )
         iBufferLen = len( lpBuffer )

retVal = zzx_TCPRead( hSocket, lpBuffer, iBufferLen )

end

call zzx_TCPClose( hSocket )

end

[Top]

zzx_TCPReadLn

This function is used to read a line of data from a server. By default lines are delimited by Char(10) but it is possible to specify a different delimiter.

retVal = zzx_TCPReadLn( hSocket, lpBuffer, iBufferLen, lpDelim )

Arguments:

hSocket	Handle to an open connection (ie the value returned from zzx_TCPConnect ).
lpBuffer	Variable to read the data from the server into. This should be large enough to accept the longest line that can be returned from the server.
iBufferLen	Number of bytes contained in lpBuffer.
lpDelim	null-terminated string specifying the line delimiter. To use the default delimiter ( char(10) ) here pass a char(0) in this argument.

Returns

Returns 1 if successful, 0 otherwise.

Example

declare function zzx_TCPConnect, zzx_TCPWrite, zzx_TCPReadLn
declare subroutine zzx_TCPClose

lpDest = 'www.sprezzatura.com' : \00\
iPort = 80

hSocket = zzx_TCPConnect( lpDest, iPort )

   if hSocket then
      * // send some data to the server
      lpBuffer   = 'Some data to send' : \00\
      iBufferLen = len( lpBuffer ) - 1

retVal = zzx_TCPWrite( hSocket, lpBuffer, iBufferLen )

      if retVal then
         * // Get a line of data from the server using the default
         * // delimiter. Note that we are not expecting any line here to
         * // be longer than 2048 chars.
         lpBuffer   = str( \00\, 2048 )
         iBufferLen = len( lpBuffer )
         lpDelim    = \00\

retVal = zzx_TCPReadLn( hSocket, lpBuffer, iBufferLen, lpDelim )

end

call zzx_TCPClose( hSocket )

end

[Top]

zzx_TCPReadEx

This function is used to read data from a server.

retVal = zzx_TCPReadEx( hSocket, lpBuffer, iBufferLen,
iReadTimeout, lpErrorBuffer, iErrorBufferLen )

Arguments:

hSocket	Handle to an open connection (ie the value returned from zzx_TCPConnect ).
lpBuffer	Variable to read the data from the server into.
iBufferLen	Number of bytes contained in lpBuffer.
iReadTimeout	Number of milliseconds that the connection should wait for the peer connection to become readable using the protocol stack. Defaults to infinite (<=0).
lpErrorBuffer	Pointer to a variable to receive any error information.
iErrorBufferLen	Size of lpErrorBuffer in bytes.

Returns

Returns 1 if successful, 0 otherwise.

Example

declare function zzx_TCPConnect, zzx_TCPWrite, zzx_TCPReadEx
declare subroutine zzx_TCPClose

lpDest = 'www.sprezzatura.com' : \00\
iPort = 80

hSocket = zzx_TCPConnect( lpDest, iPort )

   if hSocket then
      * // send some data to the server
      lpBuffer   = 'Some data to send' : \00\
      iBufferLen = len( lpBuffer ) - 1

retVal = zzx_TCPWrite( hSocket, lpBuffer, iBufferLen )

      if retVal then
         * // Get some data from the server
         lpBuffer      = str( \00\, 2048 )
         iBufferLen    = len( lpBuffer )
         lpErrorText   = str( \00\, 2048 )
         iErrorTextLen = len( lpErrorText )
         iTimeOut      = 0

retVal = zzx_TCPReadEx( hSocket, lpBuffer, iBufferLen,
iTimeout, lpErrorText, iErrorTextLen )

end

call zzx_TCPClose( hSocket )

end

[Top]

zzx_TCPReadLnEx

This function is used to read a line of data from a server. By default lines are delimited by Char(10) but it is possible to specify a different delimiter.

retVal = zzx_TCPReadLn( hSocket, lpBuffer, iBufferLen, lpDelim )

Arguments:

hSocket	Handle to an open connection (ie the value returned from zzx_TCPConnect )
lpBuffer	Variable to read the data from the server into. This should be large enough to accept the longest line that can be returned from the server.
iBufferLen	Number of bytes contained in lpBuffer.
lpDelim	A null-terminated string specifying the line delimiter. To use the default delimiter ( char(10) ) here pass a char(0) in this argument.
iReadTimeout	Number of milliseconds that the connection should wait for the peer connection to become readable using the protocol stack. Defaults to infinite (<=0).
lpErrorBuffer	Pointer to a variable to receive any error information.
iErrorBufferLen	Size of lpErrorBuffer in bytes.

Returns

Returns 1 if successful, 0 otherwise.

Example

declare function zzx_TCPConnect, zzx_TCPWrite, zzx_TCPReadLnEx
declare subroutine zzx_TCPClose

lpDest = 'www.sprezzatura.com' : \00\
iPort = 80

hSocket = zzx_TCPConnect( lpDest, iPort )

   if hSocket then
      * // send some data to the server
      lpBuffer   = 'Some data to send' : \00\
      iBufferLen = len( lpBuffer ) - 1

retVal = zzx_TCPWrite( hSocket, lpBuffer, iBufferLen )

      if retVal then
         * // Get a line of data from the server using the default
         * // delimiter. Note that we are not expecting any line here to
         * // be longer than 2048 chars.
         lpBuffer      = str( \00\, 2048 )
         iBufferLen    = len( lpBuffer )
         lpDelim       = \00\
         lpErrorText   = str( \00\, 2048 )
         iErrorTextLen = len( lpErrorText )
         iTimeOut      = 0

retVal = zzx_TCPReadLnEx( hSocket, lpBuffer, iBufferLen, lpDelim,
iTimeout, lpErrorText, iErrorTextLen )

end

call zzx_TCPClose( hSocket )

end

[Top]