ClientSocket

(Engine-Level Function)

Description:	Opens a client WinSock-compliant socket stream and returns a stream value, or a numeric error code.
Returns:	Varies - see comments
Usage:	Script Only.
Function Groups:	Stream and Socket
Related to:	CloseStream | ServerSocket | SocketAttribs | SocketServerEnd | SocketServerStart | SocketWait | SRead | SWrite | LargeSocketWrite
Format:	ClientSocket(Protocol, Host, Service, TransmitLen, ReceiveLen, Flush[,ProtocolFilters, InboundPortOrStream, IPOut, PortOut, MatchRemoteUDPSourcePort])
Parameters:

     PFilter = New(2);
     PFilter[0] = New(2);
     PFilter[0][0] = "SSL";
     PFilter[0][1] = "CN=host.example.com";
     PFilter[1] = New(2);
     PFilter[1][0] = "NULL";
     PFilter[1][1] = "";

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, 2, 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); 
]