Skip to content
Titanium SDK
Version12.5.1

You are reading 12.5.1. See this page in 13.4.1.

Titanium.Network.Socket.TCP

proxyAndroidiPhoneiPadmacOSsince 1.7

Extends Titanium.IOStreamTitanium.Proxy

TCP socket that implements the Titanium.IOStream interface.

Most socket operations are asynchronous. When you create a socket, you can define callback functions to receive the results of API calls, as well as to handle incoming data.

For example, for a client-side socket, you define connected and error callback functions.

To connect to a remote host, call the socket's connect method. If the socket connects successfully, your connected callback is invoked, and you can send and receive data on the socket. If the socket connection fails, your error callback is invoked.

After a socket is connected, you can access it like any other Titanium.IOStream. Note that the socket's read and write methods may block, so in most cases you should use the asynchronous read, write and pump methods provided by the Titanium.Stream module, rather than using the socket object's read and write methods directly.

A familiarity with the basics of BSD socket programming is recommended before using sockets with Titanium.

Use the Titanium.Network.Socket.createTCP method to create a TCP socket.

Examples

Simple Socket IO using Stream.pump

The following example uses the pump method from the <Titanium.Stream> module to read data from a socket. The pump method registers a callback that is called repeatedly to process incoming data from the socket.

var socket = Ti.Network.Socket.createTCP({
    host: 'blog.example.com', port: 80,
    connected: function (e) {
        Ti.API.info('Socket opened!');
        Ti.Stream.pump(e.socket, readCallback, 1024, true);
        Ti.Stream.write(socket, Ti.createBuffer({
            value: 'GET http://blog.example.com/index.html HTTP/1.1\r\n\r\n'
        }), writeCallback);
    },
        error: function (e) {
        Ti.API.info('Error (' + e.errorCode + '): ' + e.error);
    },
});
socket.connect();

function writeCallback(e) {
    Ti.API.info('Successfully wrote to socket.');
}

function readCallback(e) {
    if (e.bytesProcessed == -1)
    {
        // Error / EOF on socket. Do any cleanup here.
        ...
    }
    try {
        if(e.buffer) {
            var received = e.buffer.toString();
            Ti.API.info('Received: ' + received);
        } else {
            Ti.API.error('Error: read callback called with no buffer!');
        }
    } catch (ex) {
        Ti.API.error(ex);
    }
}

Listening Socket Example

The following sample shows a trivial example of using a listening socket. In this case, the application simply sends messages to itself, using the loopback address.

// Hostname to listen on/connect to. Here we use the loopback
// address. iOS also supports Ti.Platform.address (the address of
// the WiFi interface).
// Android supports only the loopback address.

var hostname = '127.0.0.1';

var clientSocket = Ti.Network.Socket.createTCP({
    host : hostname,
    port : 40404,
    connected : function(e) {
        Ti.API.info('Client socket connected!');
        Ti.Stream.pump(e.socket, pumpCallback, 1024, true);
        e.socket.write(Ti.createBuffer({
            value : 'A message from a connecting socket.'
        }));
    },
    error : function(e) {
        Ti.API.info('Error (' + e.errorCode + '): ' + e.error);
    }
});

function writeCallback(e) {
    Ti.API.info('Successfully wrote to socket.');
}

function pumpCallback(e) {
    // Has the remote socket closed its end?
    if (e.bytesProcessed < 0) {
        Ti.API.info("Closing client socket.");
        clientSocket.close();
        return;
    }
    try {
        if(e.buffer) {
            var received = e.buffer.toString();
            Ti.API.info('Received: ' + received);
        } else {
            Ti.API.error('Error: read callback called with no buffer!');
        }
    } catch (ex) {
        Ti.API.error(ex);
    }
}

// Create a socket and listen for incoming connections
var listenSocket = Ti.Network.Socket.createTCP({
    host : hostname,
    port : 40404,
    accepted : function(e) {
        // This where you would usually store the newly-connected socket, e.inbound
        // so it can be used for read / write operations elsewhere in the app.
        // In this case, we simply send a message then close the socket.
        Ti.API.info("Listening socket <" + e.socket + "> accepted incoming connection <" + e.inbound + ">");
        e.inbound.write(Ti.createBuffer({
            value : 'You have been connected to a listening socket.\r\n'
        }));
        e.inbound.close();
        // close the accepted socket

    },
    error : function(e) {
        Ti.API.error("Socket <" + e.socket + "> encountered error when listening");
        Ti.API.error(" error code <" + e.errorCode + ">");
        Ti.API.error(" error description <" + e.error + ">");
    }
});
// Starts the socket listening for connections, does not accept them
listenSocket.listen();
Ti.API.info("Listening now...");

// Tells socket to accept the next inbound connection. listenSocket.accepted gets
// called when a connection is accepted via accept()
Ti.API.info("Calling accept.");
listenSocket.accept({
    timeout : 10000
});

// Call connect after a short timeout to ensure the listening socket is ready to go.
Ti.API.info("Setting timer to connect.");
setTimeout(function(e)
{
    Ti.API.info("Calling connect on client socket.");
    clientSocket.connect();
}, 500);

Properties 12

accepted

Callback<AcceptedCallbackArgs>

Callback to be fired when a listener accepts a connection.

apiName

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

Indicates if the proxy will bubble an event to its parent.

Default: true

connected

Callback<ConnectedCallbackArgs>

Callback to be fired when the socket enters the "connected" state.

Only invoked following a successful connect call.

Can only be modified when this socket is in the INITIALIZED state.

host

String

The host to connect to or listen on.

Can only be modified when this socket is in the INITIALIZED state.

Supports both IPv4 and IPv6 addresses.

Max number of pending incoming connections to be allowed when the socket is in the LISTENING state.

Any incoming connections received while the max number of pending connections has been reached will be rejected.

port

Number

The port to connect to or listen on.

Can only be modified when this socket is in the INITIALIZED state.

secure

BooleanAndroidsince 12.1.0

Creates a secure socket.

Default: false

timeout

Number

Timeout, in milliseconds, for connect and all write operations.

Can only be modified when this socket is in the INITIALIZED state.

Methods 12

Tells a LISTENING socket to accept a connection request at the top of a listener's request queue when one becomes available.

Nonblocking; if there are no connections in the queue, sets a flag so that the socket accepts the next incoming connection immediately.

Takes an argument, an AcceptDict object which assigns options to the new connection. If the socket is already flagged to accept the next connection, the existing accept options will be updated to use the newly specified options object.

The accepted callback is called when a new connection is accepted as a result of calling accept. The callback argument holds a reference to a new socket, representing the accepted connection.

Note that the connected callback is not called on the newly created socket. This is because the socket is created in the CONNECTED state, so it never transitions to the CONNECTED state.

Throws an exception if called on a socket that is not in a LISTENING state.

Parameters
ParametersTypeDescription
optionsAcceptDict

Options to be set on next accepted socket.

2 fields
error Callback<ErrorCallbackArgs>

Callback to be fired when the socket enters the ERROR state.

timeout Number

Timeout, in milliseconds, for all write operations.

Inherited from Titanium.Proxy

Adds the specified callback as an event listener for the named event.

Parameters
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

Callback function to invoke when the event is fired.

4 fields
bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

Attempts to connect the socket to its host/port.

Throws an exception if the socket is in a CONNECTED or LISTENING state. Throws an exception if a valid host and port has not been set on this socket.

Nonblocking; connection attempts are asynchronous.

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

Parameters
ParametersTypeDescription
nameString

Name of the event.

event?Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Inherited from Titanium.IOStream

Indicates whether this stream is readable.

Returns Boolean

True if stream is readable, false otherwise.

Inherited from Titanium.IOStream

Indicates whether this stream is writable.

Returns Boolean

True if stream is writable, false otherwise.

Attempts to start listening on the socket's host/port.

The listen call will attempt to listen on the specified host and/or port property for the socket if they are set.

Nonblocking; may return before the socket is fully open and listening.

If the socket is already in a LISTENING or CONNECTED state, listen throws an exception and sets the socket state to ERROR, but does not fire the error callback.

Any error encountered after the socket starts listening results in the error callback being fired.

Inherited from Titanium.IOStream

Reads data from this stream into a buffer.

Parameters
ParametersTypeDescription
bufferTitanium.Buffer

Buffer to read stream data into.

offset?Number

Offset into the buffer to start writing stream data. If specified, length must also be specified.

length?Number

Maximum number of bytes to read. If specified, offset must also be specified.

resultsCallback?Callback<ReadCallbackArgs>

Function to call with the results of the read operation.

Returns Number

Number of bytes read.

Inherited from Titanium.Proxy

Removes the specified callback as an event listener for the named event.

Parameters
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

4 fields
bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

Inherited from Titanium.IOStream

Writes data from a buffer to this stream.

Parameters
ParametersTypeDescription
bufferTitanium.Buffer

Buffer to write to this stream.

offset?Number

Offset in the buffer of the first byte to write to the stream. If specified, length must also be specified.

length?Number

Maximum number of bytes to write to the stream. If specified, offset must also be specified.

resultsCallback?Callback<WriteCallbackArgs>

Function to call with the results of the write operation.

Returns Number

Number of bytes written.