Overview

1. Create a TCPConnection object using Engines.TCP.newConnection().
2. Open a connecting using TCPConnection.open().
3. Send data using TCPConnection.send().
4. Read incoming data using TCPConnection.receive().
5. Call TCPConnection.close() to close the connection.

Klip Security Model

   <setup>
     <scriptmode>
       extended
     </scriptmode>
   </setup>
 

In order to use this object without the Developer Mode turned on, you must have your Klip digitally signed by Klipfolio Inc.

Example

<klip>
   <identity>
      <title>
         API: TCPConnection
      </title>
   </identity>
   <locations>
      <contentsource>
         http://support.klipfolio.com/files/demo/demo.xml
      </contentsource>
      <icon>
         http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
      </icon>
      <banner>
         http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png   
      </banner>
   </locations>
   <setup>
      <scriptmode>
         extended
      </scriptmode>
   </setup>
   <klipscript>
   <![CDATA[

//
// A simple TCP/IP to connect to the HTTP server at www.serence.com.
//
// Note: To run this script, you must
//  - enable on developer mode
//  - add <scriptmode>extended</scriptmode> to the Klip's <setup>
//
function onRefresh()
{  
    _t( "onRefresh() ..." );  
    var tcp = Engines.TCP.newConnection( "www.serence.com", 80 );              // 1
    _t( "Attempting to connect to (" + tcp.host + ", " + tcp.port + ")..." );  


    if( tcp.open() )                                                           // 2
    {
        var text = "GET / HTTP/1.0\r\n\r\n";
     
        _t( "Connected!\r\n" );      
        _t( "Sending:\r\n" + text + "\r\n" );
        tcp.send( text, text.length )                                          // 3
      
        while( tcp.isConnected() ) 
        {
            Klip.delay( 500 );
            if( (data = tcp.receive( 8192 )) != null && data.length)           // 4
            {
                _t( "Received:\r\n" + data);
            }
        }
    }
  
    tcp.close();                                                               // 5
    _t( "\r\n\r\n... closed" );
  
    // Put one line message to Klip that the user should check the
    // Debug Window
	var xml = "<xml><item><link></link><description>" +
    		  "(See Debug Window for output)" +
    	      "</description></item></xml>";
    	    
    _t( "... onRefresh()" );  
	return Engines.Data.process( xml );
}

//
// Trace code
//
function _t( s )
{
    trace( s + "\r\n" );
}

   ]]>
   </klipscript>
</klip>

     	

 onRefresh() ...
 Attempting to connect to (www.serence.com, 80)...
 Connected!
 
 Sending:
 GET / HTTP/1.0
 
 
 
 Received:
 HTTP/1.1 302 Moved Temporarily
 Server: Zeus/4.3
 Date: Tue, 05 Aug 2008 17:05:52 GMT
 Connection: close
 Location: http://www.klipfarm.com/farm.php
 X-Powered-By: PHP/4.3.10-20041216
 Content-Type: text/html
 Expires: Wed, 06 Aug 2008 17:05:52 GMT
 Cache-Control: max-age=86400
 
 
 
 
 ... closed
 ... onRefresh()
 

Function Detail

close

boolean close()

Close the TCP connection. Closing an open TCP connection causes the connection to be dropped and any buffered I/O to be discarded.

Closing the same connection more than once does nothing and does not generate errors.

Returns:
true if the connection was successfully closed, false otherwise

isConnected

boolean isConnected()

Tests whether the TCP connection is still connected.

Returns:
true if the connection is currently open, false otherwise

open

boolean open( <String> host, <integer> port )

Open the TCP connection. Opening the TCP connection will attempt to establish a connection to the specified host and port.

Opening the same connection object closes any previously opened connection from this object. The host and port do not have to be the same as the previously opened connection.

Parameters:
host - either the host or IP address for the remote server. (Note that the host name must be without protocol, i.e. 'www.serence.com', not 'http://www.serence.com/')
port - the port (between 1 and 65535) to connect to on the remote server

Returns:
true if the connection was successfully established, false if the connection was refused or the host not found

receive

String receive( [<integer> length] )

Receives data over an open TCP connection. Receiving data over an open TCP connection is a non-blocking operation.

A receive request reads from buffered data accumulated from the remote server.

If the buffer is empty an empty string is returned. If the buffer contains less data than is requested, only the data in the buffer will be returned. Check the returned string's length for information about the amount of data returned.

If the connection is closed, this function returns null.

Parameters:
length - the desired length of the data to be received from the remote server (default 8192) [optional]

Returns:
string as much data as is available at the time this function is called up to the maximum length specified. An empty string is returned if no data is available. null is returned if the connection is closed.

send

boolean send( <String> data, <integer> length )

Sends data over an open TCP connection. Sending data over an open TCP connection is a blocking operation.

Note that your string can contain binary data.

Parameters:
data - the data to send to the remote server
length - the length of the data to send to the remote server

Returns:
true if the data was successfully sent, false otherwise