IpSocket

Description

The IpSocket object is the base object for TcpSocket and UdpSocket and provides all common socket functionality.

TCP (Transmission Control Protocol) is a reliable, stream-oriented, connection-oriented transport protocol. UDP (User Datagram Protocol) is an unreliable, datagram-oriented, connectionless protocol. In practice, this means that TCP is better suited for continuous transmission of data, whereas the more lightweight UDP can be used when reliability isn’t important.

The IpSocket API unifies most of the differences between the two protocols. For example, although UDP is connectionless, connectToHost() establishes a virtual connection for UDP sockets, enabling you to use the socket in more or less the same way regardless of the underlying protocol. Internally, UdpSocket remembers the address and port and functions like IoDevice.read() and IoDevice.write() use these values.

This object was introduced in InCore 2.3.

› Inherits:IoDevice › Inherited by:TcpSocket, UdpSocket

Overview

Properties

autoConnect error errorString hostname keepAlive lowDelay multicastLoopback multicastTtl pathMtu port protocol

receiveBufferSize sendBufferSize state typeOfService IoDevice.append IoDevice.atEnd IoDevice.autoOpen IoDevice.bytesAvailable IoDevice.canReadLine IoDevice.deviceErrorString

IoDevice.isOpen IoDevice.isWritable IoDevice.nameArgument IoDevice.pos IoDevice.readOnly IoDevice.size IoDevice.truncate IoDevice.unbuffered Object.objectId Object.parent

Methods

abort() connectToHost() disconnectFromHost() IoDevice.close() IoDevice.flush() IoDevice.open()

IoDevice.peekAll() IoDevice.read() IoDevice.readAll() IoDevice.readLine() IoDevice.sync()

IoDevice.write() Object.deserializeProperties() Object.fromJson() Object.serializeProperties() Object.toJson()

Signals

connected() disconnected() errorOccurred() IoDevice.lineAvailableForRead() IoDevice.readyRead() Object.completed()

Enumerations

Error Protocol State

Properties

autoConnect

This property holds whether the TCP connection should be established automatically. Keeping this option enabled will also make the object reconnect on connection errors.

› Type:Boolean › Default:true › Signal:autoConnectChanged() › Attributes:Writable

error

This property holds the most recently occurred error or IpSocket.NoError if no error occurred. If the same error occurs multiple times this property does not change. Use the errorOccurred() signal to detect multiple occurrences of the same error.

› Type:Error › Signal:errorChanged() › Attributes:Readonly

errorString

This property holds the current human readable error string corresponding to the current value in the error property. It may include additional information such as failure reasons or locations.

› Type:String › Signal:errorStringChanged() › Attributes:Readonly

hostname

This property holds the name or address of the host which to establish an IP connection to.

› Type:String › Signal:hostnameChanged() › Attributes:Writable

keepAlive

This property holds whether to enable the SO_KEEPALIVE socket option.

› Type:Boolean › Default:false › Signal:keepAliveChanged() › Attributes:Writable

lowDelay

This property holds whether to optimize the socket for low latency. For TCP connections this sets the TCP_NODELAY option and disable Nagle’s algorithm.

› Type:Boolean › Default:false › Signal:lowDelayChanged() › Attributes:Writable

multicastLoopback

This property holds whether to enable the IP_MULTICAST_LOOP (multicast loopback) socket option.

› Type:Boolean › Default:false › Signal:multicastLoopbackChanged() › Attributes:Writable

multicastTtl

This property holds an integer value to set IP_MULTICAST_TTL (TTL for multicast datagrams) socket option.

› Type:SignedInteger › Default:0 › Signal:multicastTtlChanged() › Attributes:Writable

pathMtu

This property holds the Path Maximum Transmission Unit (PMTU) value currently known by the IP stack, if any. The value can be changed for IPv6 connections only, affecting the MTU for transmission.

› Type:SignedInteger › Default:0 › Signal:pathMtuChanged() › Attributes:Writable

port

This property holds the network port number of the host which to establish an IP connection to.

› Type:SignedInteger › Default:-1 › Signal:portChanged() › Attributes:Writable

protocol

This property holds network layer protocol to use for the IP connection.

› Type:Protocol › Default:IpSocket.AnyIPProtocol › Signal:protocolChanged() › Attributes:Writable

receiveBufferSize

This property holds the socket receive buffer size in bytes at the OS level. This maps to the SO_RCVBUF socket option.

› Type:SignedInteger › Default:0 › Signal:receiveBufferSizeChanged() › Attributes:Writable

sendBufferSize

This property holds the socket send buffer size in bytes at the OS level. This maps to the SO_SNDBUF socket option.

› Type:SignedInteger › Default:0 › Signal:sendBufferSizeChanged() › Attributes:Writable

state

This property holds the current state of the IP connection.

› Type:State › Default:IpSocket.Disconnected › Signal:stateChanged() › Attributes:Writable

typeOfService

This property holds the value for the IP_TOS. See the TypeOfService table for supported values.

› Type:SignedInteger › Default:0 › Signal:typeOfServiceChanged() › Attributes:Writable

Methods

abort()

This method aborts the current connection and resets the socket. Unlike disconnectFromHost(), this function immediately closes the socket, discarding any pending data in the write buffer.

connectToHost()

This method attempts to make a connection to hostname on the given port. The protocol property is used to specify which network protocol to use (e.g. IPv4 or IPv6).

The socket is opened in the given openMode and first enters IpSocket.HostLookup state, then performs a host name lookup of hostname. If the lookup succeeds, the socket enters IpSocket.Connecting state. It then attempts to connect to the address or addresses returned by the lookup. Finally, if a connection is established, the socket enters IpSocket.Connected and emits the connected() signal.

At any point, the socket can emit the errorOccurred() signal.

disconnectFromHost()

This method attempts to close the socket. If there is pending data waiting to be written, the socket will enter IpSocket.Closing state and wait until all data has been written. Eventually, it will enter IpSocket.Disconnected and emit the disconnected() signal.

Signals

connected()

This signal is emitted after a connection has been established successfully.

disconnected()

This signal is emitted when the socket has been disconnected.

errorOccurred()

This signal is emitted whenever an error has occurred, regardless of whether the error property has changed or not. In contrast to the change notification signal of the error property this signal is also emitted several times if a certain error occurs several times in succession.

Enumerations

Error

This enumeration describes all errors which can occur in IpSocket objects. The most recently occurred error is stored in the error property.

Name	Value	Description
IpSocket.NoError	0	No error occurred or was detected.
IpSocket.EmptyHostNameError	1	No/empty hostname specified.
IpSocket.PortNumberOutOfRangeError	2	Port number out of range (1–65535).
IpSocket.DatagramWriteError	3	The specified datagram is invalid and therefore could not be written.
IpSocket.ConnectionRefusedError	10	The connection was refused by the peer (or timed out).
IpSocket.RemoteHostClosedError	11	The remote host closed the connection. Note that the client socket (i.e., this socket) will be closed after the remote close notification has been sent.
IpSocket.HostNotFoundError	12	The host address was not found.
IpSocket.SocketAccessError	13	The socket operation failed because the application lacked the required privileges.
IpSocket.SocketResourceError	14	The local system ran out of resources (e.g., too many sockets).
IpSocket.SocketTimeoutError	15	The socket operation timed out.
IpSocket.DatagramTooLargeError	16	The datagram was larger than the operating system’s limit (which can be as low as 8192 bytes).
IpSocket.NetworkError	17	An error occurred with the network (e.g., the network cable was accidentally plugged out).
IpSocket.AddressInUseError	18	The address specified to bind is already in use and was set to be exclusive.
IpSocket.SocketAddressNotAvailableError	19	The address specified to bind does not belong to the host.
IpSocket.UnsupportedSocketOperationError	20	The requested socket operation is not supported by the local operating system (e.g., lack of IPv6 support).
IpSocket.UnfinishedSocketOperationError	21	The last operation attempted has not finished yet (still in progress in the background).
IpSocket.ProxyAuthenticationRequiredError	22	The socket is using a proxy, and the proxy requires authentication.
IpSocket.SslHandshakeFailedError	23	The SSL/TLS handshake failed, so the connection was closed (only used in SslSocket).
IpSocket.ProxyConnectionRefusedError	24	Could not contact the proxy server because the connection to that server was denied.
IpSocket.ProxyConnectionClosedError	25	The connection to the proxy server was closed unexpectedly (before the connection to the final peer was established).
IpSocket.ProxyConnectionTimeoutError	26	The connection to the proxy server timed out or the proxy server stopped responding in the authentication phase.
IpSocket.ProxyNotFoundError	27	The proxy address (or the application proxy) was not found.
IpSocket.ProxyProtocolError	28	The connection negotiation with the proxy server failed, because the response from the proxy server could not be understood.
IpSocket.OperationError	29	An operation was attempted while the socket was in a state that did not permit it.
IpSocket.SslInternalError	30	The SSL library being used reported an internal error. This is probably the result of a bad installation or misconfiguration of the library.
IpSocket.SslInvalidUserDataError	31	Invalid data (certificate, key, cypher, etc.) was provided and its use resulted in an error in the SSL library.
IpSocket.TemporaryError	32	A temporary error occurred (e.g., operation would block and socket is non-blocking).

Protocol

This enumeration describes the network layer protocol values supported by IpSocket-based objects.

Name	Value	Description
IpSocket.UnknownProtocol	-1	Other than IPv4 and IPv6.
IpSocket.IPv4Protocol	0	IPv4.
IpSocket.IPv6Protocol	1	IPv6.
IpSocket.AnyIPProtocol	2	Either IPv4 or IPv6.

State

This enumeration describes the different states in which a socket can be.

Name	Value	Description
IpSocket.Disconnected	0	The socket is not connected.
IpSocket.HostLookup	1	The socket is performing a host name lookup.
IpSocket.Connecting	2	The socket has started establishing a connection.
IpSocket.Connected	3	A connection is established.
IpSocket.Bound	4	The socket is bound to an address and port.
IpSocket.Closing	6	The socket is about to close (data may still be waiting to be written).