docs/Classes/SocketIOClient.html
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 /.
Swift
public let nsp: String
`
anyHandler
`
A handler that will be called on any event.
Swift
public private(set) var anyHandler: ((SocketAnyEvent) -> ())? { get }
`
handlers
`
The array of handlers for this socket.
Swift
public private(set) var handlers: [SocketEventHandler] { get }
`
manager
`
The manager for this socket.
Swift
public private(set) weak var manager: SocketManagerSpec? { get }
`
rawEmitView
`
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.
Swift
public private(set) lazy var rawEmitView: SocketRawView { get set }
`
status
`
The status of this client.
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.
Swift
public private(set) var sid: String? { get }
Initializers
`
init(manager:nsp:)
`
Type safe way to create a new SocketIOClient. opts can be omitted.
Swift
public init(manager: SocketManagerSpec, nsp: String)
| manager |
The manager for this socket.
|
| nsp |
The namespace of the socket.
|
Methods
`
connect(withPayload:)
`
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.
Swift
open func connect(withPayload payload: [String : Any]? = nil)
| withPayload |
An optional payload sent on connect
|
`
connect(withPayload:timeoutAfter:withHandler:)
`
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.
Swift
open func connect(withPayload payload: [String : Any]? = nil, timeoutAfter: Double, withHandler handler: (() -> ())?)
| 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.
|
`
didConnect(toNamespace:payload:)
`
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.
Swift
open func didConnect(toNamespace namespace: String, payload: [String : Any]?)
| toNamespace |
The namespace that was connected to.
|
`
didDisconnect(reason:)
`
Called when the client has disconnected from socket.io.
Swift
open func didDisconnect(reason: String)
| reason |
The reason for the disconnection.
|
`
disconnect()
`
Disconnects the socket.
This will cause the socket to leave the namespace it is associated to, as well as remove itself from the manager.
Swift
open func disconnect()
`
emit(_:_:completion:)
`
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]
Swift
open func emit(_ event: String, _ items: SocketData..., completion: (() -> ())? = nil)
| event |
The event to send.
|
| items |
The items to send with this event. May be left out.
|
| completion |
Callback called on transport write completion.
|
`
emitWithAck(_:_:)
`
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
...
}
Swift
open func emitWithAck(_ event: String, _ items: SocketData...) -> OnAckCallback
| event |
The event to send.
|
| items |
The items to send with this event. May be left out.
|
An OnAckCallback. You must call the timingOut(after:) method before the event will be sent.
`
emitAck(_:with:)
`
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.
Swift
open func emitAck(_ ack: Int, with items: [Any])
| ack |
The ack number.
|
| with |
The data for this ack.
|
`
handleAck(_:data:)
`
Called when socket.io has acked one of our emits. Causes the corresponding ack callback to be called.
Swift
open func handleAck(_ ack: Int, data: [Any])
| ack |
The number for this ack.
|
| data |
The data sent back with this ack.
|
`
handleClientEvent(_:data:)
`
Called on socket.io specific events.
Swift
open func handleClientEvent(_ event: SocketClientEvent, data: [Any])
| event |
The SocketClientEvent.
|
| data |
The data for this event.
|
`
handleEvent(_:data:isInternalMessage:withAck:)
`
Called when we get an event from socket.io.
Swift
open func handleEvent(_ event: String, data: [Any], isInternalMessage: Bool, withAck ack: Int = -1)
| 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.
|
`
handlePacket(_:)
`
Causes a client to handle a socket.io packet. The namespace for the packet must match the namespace of the socket.
Swift
open func handlePacket(_ packet: SocketPacket)
| packet |
The packet to handle.
|
`
leaveNamespace()
`
Call when you wish to leave a namespace and disconnect this socket.
Swift
open func leaveNamespace()
`
joinNamespace(withPayload:)
`
Joins nsp. You shouldn’t need to call this directly, instead call connect.
Swift
open func joinNamespace(withPayload payload: [String : Any]? = nil)
| withPayload |
An optional payload sent on connect
|
`
off(clientEvent:)
`
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.
Swift
open func off(clientEvent event: SocketClientEvent)
| clientEvent |
The event to remove handlers for.
|
`
off(_:)
`
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.
Swift
open func off(_ event: String)
| event |
The event to remove handlers for.
|
`
off(id:)
`
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.
Swift
open func off(id: UUID)
| id |
The UUID of the handler you wish to remove.
|
`
on(_:callback:)
`
Adds a handler for an event.
Swift
@discardableResult
open func on(_ event: String, callback: @escaping NormalCallback) -> UUID
| event |
The event name for this handler.
|
| callback |
The callback that will execute when this event is received.
|
A unique id for the handler that can be used to remove it.
`
on(clientEvent:callback:)
`
Adds a handler for a client event.
Example:
socket.on(clientEvent: .connect) {data, ack in
...
}
Swift
@discardableResult
open func on(clientEvent event: SocketClientEvent, callback: @escaping NormalCallback) -> UUID
| event |
The event for this handler.
|
| callback |
The callback that will execute when this event is received.
|
A unique id for the handler that can be used to remove it.
`
once(clientEvent:callback:)
`
Adds a single-use handler for a client event.
Swift
@discardableResult
open func once(clientEvent event: SocketClientEvent, callback: @escaping NormalCallback) -> UUID
| clientEvent |
The event for this handler.
|
| callback |
The callback that will execute when this event is received.
|
A unique id for the handler that can be used to remove it.
`
once(_:callback:)
`
Adds a single-use handler for an event.
Swift
@discardableResult
open func once(_ event: String, callback: @escaping NormalCallback) -> UUID
| event |
The event name for this handler.
|
| callback |
The callback that will execute when this event is received.
|
A unique id for the handler that can be used to remove it.
`
onAny(_:)
`
Adds a handler that will be called on every event.
Swift
open func onAny(_ handler: @escaping (SocketAnyEvent) -> ())
| handler |
The callback that will execute whenever an event is received.
|
`
removeAllHandlers()
`
Removes all handlers.
Can be used after disconnecting to break any potential remaining retain cycles.
Swift
open func removeAllHandlers()
`
setReconnecting(reason:)
`
Puts the socket back into the connecting state. Called when the manager detects a broken connection, or when a manual reconnect is triggered.
Swift
open func setReconnecting(reason: String)
| reason |
The reason this socket is reconnecting.
|