SocketIOClient

open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, SocketParsable

The main class for SocketIOClientSwift.

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

Represents a socket.io-client. Most interaction with socket.io will be through this class.

  • If true then every time connect is called, a new engine will be created.

    Declaration

    Swift

    public var forceNew = false
  • The queue that all interaction with the client should occur on. This is the queue that event handlers are called on.

    Declaration

    Swift

    public var handleQueue = DispatchQueue.main
  • nsp

    The namespace that this socket is currently connected to.

    Must start with a /.

    Declaration

    Swift

    public var nsp = "/"
  • The configuration for this client.

    This cannot be set after calling one of the connect methods.

    Declaration

    Swift

    public var config: SocketIOClientConfiguration
  • If true, this client will try and reconnect on any disconnects.

    Declaration

    Swift

    public var reconnects = true
  • The number of seconds to wait before attempting to reconnect.

    Declaration

    Swift

    public var reconnectWait = 10
  • sid

    The session id of this client.

    Declaration

    Swift

    public var sid: String?
  • The URL of the socket.io server.

    If changed after calling init, forceNew must be set to true, or it will only connect to the url set in the init.

    Declaration

    Swift

    public var socketURL: URL
  • A list of packets that are waiting for binary data.

    The way that socket.io works all data should be sent directly after each packet. So this should ideally be an array of one packet waiting for data.

    This should not be modified directly.

    Declaration

    Swift

    public var waitingPackets = [SocketPacket]()
  • A handler that will be called on any event.

    Declaration

    Swift

    public private(set) var anyHandler: ((SocketAnyEvent) -> ())?
  • The engine for this client.

    Declaration

    Swift

    public internal(set) var engine: SocketEngineSpec?
  • The array of handlers for this socket.

    Declaration

    Swift

    public private(set) var handlers = [SocketEventHandler]()
  • The status of this client.

    Declaration

    Swift

    public private(set) var status = SocketIOClientStatus.notConnected
  • Type safe way to create a new SocketIOClient. opts can be omitted.

    Declaration

    Swift

    public init(socketURL: URL, config: SocketIOClientConfiguration = [])

    Parameters

    socketURL

    The url of the socket.io server.

    config

    The config for this socket.

  • Not so type safe way to create a SocketIOClient, meant for Objective-C compatiblity. If using Swift it’s recommended to use init(socketURL: NSURL, options: Set<SocketIOClientOption>)

    Declaration

    Swift

    public convenience init(socketURL: NSURL, config: NSDictionary?)

    Parameters

    socketURL

    The url of the socket.io server.

    config

    The config for this socket.

  • 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()
  • 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(timeoutAfter: Double, withHandler handler: (() -> ())?)

    Parameters

    timeoutAfter

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

    withHandler

    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)

    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.

    Declaration

    Swift

    open func disconnect()
  • Send an event to the server, with optional data items.

    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...)

    Parameters

    event

    The event to send.

    items

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

  • Same as emit, but meant for Objective-C

    Declaration

    Swift

    open func emit(_ event: String, with items: [Any])

    Parameters

    event

    The event to send.

    with

    The items to send with this event. Send an empty array to send no data.

  • 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.

  • Same as emitWithAck, but for Objective-C

    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.

    Example:

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

    Declaration

    Swift

    open func emitWithAck(_ event: String, with items: [Any]) -> OnAckCallback

    Parameters

    event

    The event to send.

    with

    The items to send with this event. Use [] to send nothing.

    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 the engine closes.

    Declaration

    Swift

    open func engineDidClose(reason: String)

    Parameters

    reason

    The reason that the engine closed.

  • Called when the engine errors.

    Declaration

    Swift

    open func engineDidError(reason: String)

    Parameters

    reason

    The reason the engine errored.

  • Called when the engine opens.

    Declaration

    Swift

    open func engineDidOpen(reason: String)

    Parameters

    reason

    The reason the engine opened.

  • 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 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.

    withAck

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

  • Called on socket.io specific events.

    Declaration

    Swift

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

    Parameters

    event
    data

    The data for this event.

  • Call when you wish to leave a namespace and return to the default namespace.

    Declaration

    Swift

    open func leaveNamespace()
  • Joins namespace.

    Do not use this to join the default namespace. Instead call leaveNamespace.

    Declaration

    Swift

    open func joinNamespace(_ namespace: String)

    Parameters

    namespace

    The namespace to join.

  • 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

    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

    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

    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

    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.

  • Called when the engine has a message that must be parsed.

    Declaration

    Swift

    public func parseEngineMessage(_ msg: String)

    Parameters

    msg

    The message that needs parsing.

  • Called when the engine receives binary data.

    Declaration

    Swift

    public func parseEngineBinaryData(_ data: Data)

    Parameters

    data

    The data the engine received.

  • Tries to reconnect to the server.

    This will cause a disconnect event to be emitted, as well as an reconnectAttempt event.

    Declaration

    Swift

    open func reconnect()
  • Removes all handlers.

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

    Declaration

    Swift

    open func removeAllHandlers()