ClientSocket

Description: This function opens a client WinSock-compliant socket stream and returns a stream value, or a numeric error code.

Returns: Varies – see comments

Usage: Script

Format: ClientSocket(Protocol, Host, Service, TransmitLen, ReceiveLen, Flush[,ProtocolFilters, InboundPortOrStream, IPOut, PortOut)

Parameters: Protocol { numeric } { required } { no default: }

Any numeric expression giving the protocol to be used. This must be a valid 0 for TCP/IP protocol or a valid 1 for a UDP protocol.

Host { text } { required } { no default: }

Any text expression giving the host name or TCP/IP address to connect.

Service { varies } { required } { no default: }

Either any text expression giving the service name to connect, or any numeric expression giving the port number with which to connect.

TransmitLen { numeric } { required } { no default: }

(Deprecated) Any numeric expression for the number of bytes to buffer when transmitting. This value should be the maximum number of bytes plus 1024 (1k); the minimum acceptable value is 1024.

ReceiveLen { numeric } { required } { no default: }

Any numeric expression for the maximum number of bytes to buffer by VTS when receiving. Additional buffering will be handled by WinSock. This value should be the maximum number of bytes plus 1024 (1 k); the minimum acceptable value is 1024.

Flush { Boolean } { required } { no default: }

Any logical expression. If true, the transmit buffer will be flushed (transmitted) after each write to the stream. This normally should be false to reduce network traffic by allowing the driver to group smaller packets into a single larger packet.

ProtocolFilters { 2D array } { optional } { no default: }

Represents a stack of engine protocol filters and their parameters. These filters are used to process or modify data before transmission or after reception.

InboundPortOrStream { stream } { optional } { no default: }

An optional parameter, used only in connection with a UDP connection. If set, this should be an existing UDP stream as returned from a ServerSocket, for the same remote IP as is being connected to. Incoming UDP datagrams on the ServerSocket stream will continue to be received, but the stream can also be used for datagram transmission. If InboundPortOrStream is not a stream, it is interpreted as a local port number on which to listen for inbound datagrams. The stream returned by ClientSocket can be used, in both cases, for datagram transmission and reception.

IPOut { text } { optional } { no default: }

An optional parameter used to identify the IP of the network interface card from which to transmit UDP datagrams. LocalIP s of use on multi-homed machines to identify the physical IP binding to use.

PortOut { text } { optional } { no default: }

An optional parameter used to identify the local port from which to transmit UDP datagrams

Comments: This function will return its (integer) socket number when the socket is created but not yet connected, a stream value when the connection is made, or a short integer error code. If the socket connection is lost (server shutdown ) the stream is closed and set invalid ( no error code returned).

Error Code	Description
10061	Cannot connect to Host at port number specified
11004	Cannot find requested host

The client socket function has a slightly different behavior, depending on whether the connection is made via TCP or UDP. The difference is explained in the following two diagrams

Client Sockets on TCP:

1. A ClientSocket statement runs and returns an integer value.

2. An outbound connection is made.

3. When the connection is established, the stream is triggered.

4. The stream trigger causes the value returned from 1 to become a stream value.

• If the connection attempt fails at any point, the value returned from 1 will become a negative integer, representing an error code

Client Sockets on UDP:

1. A ClientSocket statement runs and returns a stream value.

2. Stream writing statements are used to write data to the stream

3. A UDP datagram is issued to the target device each time a write is done by script code.

Example:

Init [

If 1 Main;

[

client = ClientSocket(0 { TCP/IP protocol },

"WServer" { Host },

20000 { Port number },

1024, 1024 { Buffering },

1 { Flush after writes });

]

Main [

{ If stream connection lost, retry connection }

If TimeOut(! Valid(client), 2) Init;

{ Exit if return value valid and not a stream }

If ValueType(client) != 8 Error;

{ Read stream data as received or on demand with "r" key }

If GetStreamLength(client) > 0 || MatchKeys(2, "r");

[

SRead(client, Concat("%", Concat(GetStreamLength(client),

"c")), data);

]

{ Write stream data to server every second }

If TimeOut(1, 1);

[

SWrite(client, "%s", Concat(" Hello World ",

Time(Seconds(), 3)));

]

{ Close stream if window closed, then stop }

If WindowClose(Self());

[

CloseStream(client);

Slay(Self(), 1) ;

]

{ Display received data and connection status }

ZText(10, 150, data, 15, 0);

ZText(200, 100, Cond(ValueType(client) == 8,

"Connected", "Not Connected"), 10, 0);

]

Error [

{ Display error code }

ZText(100, 130, Concat("Client error code : ", client),

10, 0);

]