SocketIOClient

open class SocketIOClient : NSObject, SocketIOClientSpec

Represents a socket.io-client.

Clients are created through a SocketManager, which owns the SocketEngineSpec that controls the connection to the server.

For example:

// Create a socket for the /swift namespace
let socket = manager.socket(forNamespace: "/swift")

// Add some handlers and connect

NOTE: The client is not thread/queue safe, all interaction with the socket should be done on the manager.handleQueue

Properties

  • nsp

    The namespace that this socket is currently connected to.

    Must start with a /.

    Declaration

    Swift

    public let nsp: String

  • A handler that will be called on any event.

    Declaration

    Swift

    public private(set) var anyHandler: ((SocketAnyEvent) -> ())? { get }

  • The array of handlers for this socket.

    Declaration

    Swift

    public private(set) var handlers: [SocketEventHandler] { get }

  • The manager for this socket.

    Declaration

    Swift

    public private(set) weak var manager: SocketManagerSpec? { get }

  • A view into this socket where emits do not check for binary data.

    Usage:

    socket.rawEmitView.emit("myEvent", myObject)

    NOTE: It is not safe to hold on to this view beyond the life of the socket.

    Declaration

    Swift

    public private(set) lazy var rawEmitView: SocketRawView { get set }

  • The status of this client.

    Declaration

    Swift

    public private(set) var status: SocketIOStatus { get set }
  • sid

    The id of this socket.io connect. This is different from the sid of the engine.io connection.

    Declaration

    Swift

    public private(set) var sid: String? { get }

Initializers

  • Type safe way to create a new SocketIOClient. opts can be omitted.

    Declaration

    Swift

    public init(manager: SocketManagerSpec, nsp: String)

    Parameters

    manager

    The manager for this socket.
    nsp

    The namespace of the socket.

Methods

  • Connect to the server. The same as calling connect(timeoutAfter:withHandler:) with a timeout of 0.

    Only call after adding your event listeners, unless you know what you’re doing.

    Declaration

    Swift

    open func connect(withPayload payload: [String : Any]? = nil)

    Parameters

    withPayload

    An optional payload sent on connect

  • Connect to the server. If we aren’t connected after timeoutAfter seconds, then withHandler is called.

    Only call after adding your event listeners, unless you know what you’re doing.

    Declaration

    Swift

    open func connect(withPayload payload: [String : Any]? = nil, timeoutAfter: Double, withHandler handler: (() -> ())?)

    Parameters

    withPayload

    An optional payload sent on connect
    timeoutAfter

    The number of seconds after which if we are not connected we assume the connection has failed. Pass 0 to never timeout.
    handler

    The handler to call when the client fails to connect.

  • Called when the client connects to a namespace. If the client was created with a namespace upfront, then this is only called when the client connects to that namespace.

    Declaration

    Swift

    open func didConnect(toNamespace namespace: String, payload: [String : Any]?)

    Parameters

    toNamespace

    The namespace that was connected to.

  • Called when the client has disconnected from socket.io.

    Declaration

    Swift

    open func didDisconnect(reason: String)

    Parameters

    reason

    The reason for the disconnection.

  • Disconnects the socket.

    This will cause the socket to leave the namespace it is associated to, as well as remove itself from the manager.

    Declaration

    Swift

    open func disconnect()

  • Send an event to the server, with optional data items and optional write completion handler.

    If an error occurs trying to transform items into their socket representation, a SocketClientEvent.error will be emitted. The structure of the error data is [eventName, items, theError]

    Declaration

    Swift

    open func emit(_ event: String, _ items: SocketData..., completion: (() -> ())? = nil)

    Parameters

    event

    The event to send.
    items

    The items to send with this event. May be left out.
    completion

    Callback called on transport write completion.

  • Sends a message to the server, requesting an ack.

    NOTE: It is up to the server send an ack back, just calling this method does not mean the server will ack. Check that your server’s api will ack the event being sent.

    If an error occurs trying to transform items into their socket representation, a SocketClientEvent.error will be emitted. The structure of the error data is [eventName, items, theError]

    Example:

    socket.emitWithAck("myEvent", 1).timingOut(after: 1) {data in
    ...
}

    Declaration

    Swift

    open func emitWithAck(_ event: String, _ items: SocketData...) -> OnAckCallback

    Parameters

    event

    The event to send.
    items

    The items to send with this event. May be left out.

    Return Value

    An OnAckCallback. You must call the timingOut(after:) method before the event will be sent.

  • Call when you wish to tell the server that you’ve received the event for ack.

    You shouldn’t need to call this directly. Instead use an SocketAckEmitter that comes in an event callback.

    Declaration

    Swift

    open func emitAck(_ ack: Int, with items: [Any])

    Parameters

    ack

    The ack number.
    with

    The data for this ack.

  • Called when socket.io has acked one of our emits. Causes the corresponding ack callback to be called.

    Declaration

    Swift

    open func handleAck(_ ack: Int, data: [Any])

    Parameters

    ack

    The number for this ack.
    data

    The data sent back with this ack.

  • Called on socket.io specific events.

    Declaration

    Swift

    open func handleClientEvent(_ event: SocketClientEvent, data: [Any])

    Parameters

    event
    data

    The data for this event.

  • Called when we get an event from socket.io.

    Declaration

    Swift

    open func handleEvent(_ event: String, data: [Any], isInternalMessage: Bool, withAck ack: Int = -1)

    Parameters

    event

    The name of the event.
    data

    The data that was sent with this event.
    isInternalMessage

    Whether this event was sent internally. If true it is always sent to handlers.
    ack

    If > 0 then this event expects to get an ack back from the client.

  • Causes a client to handle a socket.io packet. The namespace for the packet must match the namespace of the socket.

    Declaration

    Swift

    open func handlePacket(_ packet: SocketPacket)

    Parameters

    packet

    The packet to handle.

  • Call when you wish to leave a namespace and disconnect this socket.

    Declaration

    Swift

    open func leaveNamespace()

  • Joins nsp. You shouldn’t need to call this directly, instead call connect.

    Declaration

    Swift

    open func joinNamespace(withPayload payload: [String : Any]? = nil)

    Parameters

    withPayload

    An optional payload sent on connect

  • Removes handler(s) for a client event.

    If you wish to remove a client event handler, call the off(id:) with the UUID received from its on call.

    Declaration

    Swift

    open func off(clientEvent event: SocketClientEvent)

    Parameters

    clientEvent

    The event to remove handlers for.

  • Removes handler(s) based on an event name.

    If you wish to remove a specific event, call the off(id:) with the UUID received from its on call.

    Declaration

    Swift

    open func off(_ event: String)

    Parameters

    event

    The event to remove handlers for.

  • Removes a handler with the specified UUID gotten from an on or once

    If you want to remove all events for an event, call the off off(_:) method with the event name.

    Declaration

    Swift

    open func off(id: UUID)

    Parameters

    id

    The UUID of the handler you wish to remove.

  • Adds a handler for an event.

    Declaration

    Swift

    @discardableResult
open func on(_ event: String, callback: @escaping NormalCallback) -> UUID

    Parameters

    event

    The event name for this handler.
    callback

    The callback that will execute when this event is received.

    Return Value

    A unique id for the handler that can be used to remove it.

  • Adds a handler for a client event.

    Example:

    socket.on(clientEvent: .connect) {data, ack in
    ...
}

    Declaration

    Swift

    @discardableResult
open func on(clientEvent event: SocketClientEvent, callback: @escaping NormalCallback) -> UUID

    Parameters

    event

    The event for this handler.
    callback

    The callback that will execute when this event is received.

    Return Value

    A unique id for the handler that can be used to remove it.

  • Adds a single-use handler for a client event.

    Declaration

    Swift

    @discardableResult
open func once(clientEvent event: SocketClientEvent, callback: @escaping NormalCallback) -> UUID

    Parameters

    clientEvent

    The event for this handler.
    callback

    The callback that will execute when this event is received.

    Return Value

    A unique id for the handler that can be used to remove it.

  • Adds a single-use handler for an event.

    Declaration

    Swift

    @discardableResult
open func once(_ event: String, callback: @escaping NormalCallback) -> UUID

    Parameters

    event

    The event name for this handler.
    callback

    The callback that will execute when this event is received.

    Return Value

    A unique id for the handler that can be used to remove it.

  • Adds a handler that will be called on every event.

    Declaration

    Swift

    open func onAny(_ handler: @escaping (SocketAnyEvent) -> ())

    Parameters

    handler

    The callback that will execute whenever an event is received.

  • Removes all handlers.

    Can be used after disconnecting to break any potential remaining retain cycles.

    Declaration

    Swift

    open func removeAllHandlers()

  • Puts the socket back into the connecting state. Called when the manager detects a broken connection, or when a manual reconnect is triggered.

    Declaration

    Swift

    open func setReconnecting(reason: String)

    Parameters

    reason

    The reason this socket is reconnecting.