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 timeconnect
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
-
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
-
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 totrue
, 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, thenwithHandler
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, aSocketClientEvent.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, aSocketClientEvent.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 thetimingOut(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 thetimingOut(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
The
SocketClientEvent
.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 itson
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 itson
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
oronce
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 anreconnectAttempt
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()