From 752407fb6750ab6323db6717721d399770e802da Mon Sep 17 00:00:00 2001 From: Erik Little Date: Fri, 29 Sep 2017 22:09:38 -0400 Subject: [PATCH] More documentation --- .../project.pbxproj | 4 +-- Source/SocketIO/Client/SocketIOClient.swift | 20 ++++++++++-- .../SocketIO/Client/SocketIOClientSpec.swift | 32 +++++++++++++++++++ Source/Starscream | 2 +- 4 files changed, 52 insertions(+), 6 deletions(-) diff --git a/Socket.IO-Client-Swift.xcodeproj/project.pbxproj b/Socket.IO-Client-Swift.xcodeproj/project.pbxproj index 649de36..5d836cb 100644 --- a/Socket.IO-Client-Swift.xcodeproj/project.pbxproj +++ b/Socket.IO-Client-Swift.xcodeproj/project.pbxproj @@ -990,7 +990,7 @@ ONLY_ACTIVE_ARCH = YES; PRODUCT_NAME = SocketIO; SWIFT_OPTIMIZATION_LEVEL = "-Onone"; - SWIFT_VERSION = 3.0; + SWIFT_VERSION = 4.0; TVOS_DEPLOYMENT_TARGET = 9.0; WATCHOS_DEPLOYMENT_TARGET = 2.0; }; @@ -1029,7 +1029,7 @@ MACOSX_DEPLOYMENT_TARGET = 10.10; PRODUCT_NAME = SocketIO; SWIFT_OPTIMIZATION_LEVEL = "-Owholemodule"; - SWIFT_VERSION = 3.0; + SWIFT_VERSION = 4.0; TVOS_DEPLOYMENT_TARGET = 9.0; WATCHOS_DEPLOYMENT_TARGET = 2.0; }; diff --git a/Source/SocketIO/Client/SocketIOClient.swift b/Source/SocketIO/Client/SocketIOClient.swift index 9875895..540fed0 100644 --- a/Source/SocketIO/Client/SocketIOClient.swift +++ b/Source/SocketIO/Client/SocketIOClient.swift @@ -64,7 +64,9 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So @objc public var handleQueue = DispatchQueue.main - /// The namespace for this client. + /// The namespace that this socket is currently connected to. + /// + /// **Must** start with a `/`. @objc public var nsp = "/" @@ -93,6 +95,11 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So public var socketURL: URL var ackHandlers = SocketAckManager() + + /// 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. var waitingPackets = [SocketPacket]() private(set) var currentAck = -1 @@ -172,7 +179,9 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So engine = SocketEngine(client: self, url: socketURL, config: config) } - /// Connect to the server. + /// 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. @objc open func connect() { connect(timeoutAfter: 0, withHandler: nil) @@ -180,6 +189,8 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So /// 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. + /// /// - parameter timeoutAfter: The number of seconds after which if we are not connected we assume the connection /// has failed. Pass 0 to never timeout. /// - parameter withHandler: The handler to call when the client fails to connect. @@ -219,6 +230,8 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So return OnAckCallback(ackNumber: currentAck, items: items, socket: self) } + /// 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. func didConnect(toNamespace namespace: String) { DefaultSocketLogger.Logger.log("Socket connected", type: SocketIOClient.logType) @@ -227,6 +240,7 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So handleClientEvent(.connect, data: [namespace]) } + /// Called when the client has disconnected from socket.io. func didDisconnect(reason: String) { guard status != .disconnected else { return } @@ -437,7 +451,7 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So handleEvent(event.rawValue, data: data, isInternalMessage: true) } - /// Leaves nsp and goes back to the default namespace. + /// Call when you wish to leave a namespace and return to the default namespace. @objc open func leaveNamespace() { if nsp != "/" { diff --git a/Source/SocketIO/Client/SocketIOClientSpec.swift b/Source/SocketIO/Client/SocketIOClientSpec.swift index f53525f..68e9c59 100644 --- a/Source/SocketIO/Client/SocketIOClientSpec.swift +++ b/Source/SocketIO/Client/SocketIOClientSpec.swift @@ -25,20 +25,52 @@ import Dispatch protocol SocketIOClientSpec : class { + /// The queue that all interaction with the client must be on. var handleQueue: DispatchQueue { get set } + + /// The namespace that this socket is currently connected to. + /// + /// **Must** start with a `/`. var nsp: String { get set } + + /// 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. var waitingPackets: [SocketPacket] { get set } + /// 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. func didConnect(toNamespace namespace: String) + + /// Called when the client has disconnected from socket.io. func didDisconnect(reason: String) + + /// Called when the client encounters an error. func didError(reason: String) + + /// Called when socket.io has acked one of our emits. Causes the corresponding ack callback to be called. func handleAck(_ ack: Int, data: [Any]) + + /// Called when we get an event from socket.io. func handleEvent(_ event: String, data: [Any], isInternalMessage: Bool, withAck ack: Int) + + /// Called on socket.io events. func handleClientEvent(_ event: SocketClientEvent, data: [Any]) + + /// Call when you wish to leave a namespace and return to the default namespace. + func leaveNamespace() + + /// Joins `namespace`. + /// + /// **Do not use this to join the default namespace.** Instead call `leaveNamespace`. + /// + /// - parameter namespace: The namespace to join. func joinNamespace(_ namespace: String) } extension SocketIOClientSpec { + /// Default implementation. func didError(reason: String) { DefaultSocketLogger.Logger.error("\(reason)", type: "SocketIOClient") diff --git a/Source/Starscream b/Source/Starscream index f7e28f2..9ecc44c 160000 --- a/Source/Starscream +++ b/Source/Starscream @@ -1 +1 @@ -Subproject commit f7e28f24ae20898da5804079319da52682bb9212 +Subproject commit 9ecc44c2da053b1c4ff0ac505fe1d43a793d0b45