Erik 1ff8e11a1f
Document SocketIOClientSwift
add docs

Start documenting engine

More engine documentation

Document engine

document SocketEngineClient

Document SocketEnginePollable and SocketEnginePacketType

Document SocketEngineWebsocket

Document SocketIOClient

Document SocketIOClientStatus

Document SocketLogger

Document some typealiases

Document SocketIOClientOption

Document SocketIOClientConfiguration
2017-05-06 14:41:50 -04:00

377 lines
25 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en">
<head>
<title>SocketIO Reference</title>
<link rel="stylesheet" type="text/css" href="css/jazzy.css" />
<link rel="stylesheet" type="text/css" href="css/highlight.css" />
<meta charset="utf-8">
<script src="js/jquery.min.js" defer></script>
<script src="js/jazzy.js" defer></script>
<script src="js/lunr.min.js" defer></script>
<script src="js/typeahead.jquery.js" defer></script>
<script src="js/jazzy.search.js" defer></script>
</head>
<body>
<a title="SocketIO Reference"></a>
<header class="header">
<p class="header-col header-col--primary">
<a class="header-link" href="index.html">
SocketIO Docs
</a>
(84% documented)
</p>
<p class="header-col--secondary">
<form role="search" action="search.json">
<input type="text" placeholder="Search documentation" data-typeahead>
</form>
</p>
</header>
<p class="breadcrumbs">
<a class="breadcrumb" href="index.html">SocketIO Reference</a>
<img class="carat" src="img/carat.png" />
SocketIO Reference
</p>
<div class="content-wrapper">
<nav class="navigation">
<ul class="nav-groups">
<li class="nav-group-name">
<a class="nav-group-name-link" href="Classes.html">Classes</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/OnAckCallback.html">OnAckCallback</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/SSLCert.html">SSLCert</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/SSLSecurity.html">SSLSecurity</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/SocketAckEmitter.html">SocketAckEmitter</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/SocketAnyEvent.html">SocketAnyEvent</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/SocketClientManager.html">SocketClientManager</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/SocketEngine.html">SocketEngine</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/SocketIOClient.html">SocketIOClient</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/WebSocket.html">WebSocket</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/WebSocket/CloseCode.html"> CloseCode</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="Global Variables.html">Global Variables</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="Global Variables.html#/s:v8SocketIO31WebsocketDidConnectNotificationSS">WebsocketDidConnectNotification</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Global Variables.html#/s:v8SocketIO34WebsocketDidDisconnectNotificationSS">WebsocketDidDisconnectNotification</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Global Variables.html#/s:v8SocketIO34WebsocketDisconnectionErrorKeyNameSS">WebsocketDisconnectionErrorKeyName</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="Enums.html">Enums</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="Enums/SocketAckStatus.html">SocketAckStatus</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Enums/SocketEnginePacketType.html">SocketEnginePacketType</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Enums/SocketIOClientOption.html">SocketIOClientOption</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Enums/SocketIOClientStatus.html">SocketIOClientStatus</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="Protocols.html">Protocols</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="Protocols/SSLTrustValidator.html">SSLTrustValidator</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Protocols.html#/s:P8SocketIO10SocketData">SocketData</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Protocols/SocketEngineClient.html">SocketEngineClient</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Protocols/SocketEnginePollable.html">SocketEnginePollable</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Protocols/SocketEngineSpec.html">SocketEngineSpec</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Protocols/SocketEngineWebsocket.html">SocketEngineWebsocket</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Protocols/SocketLogger.html">SocketLogger</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Protocols/WebSocketDelegate.html">WebSocketDelegate</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Protocols/WebSocketPongDelegate.html">WebSocketPongDelegate</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="Structs.html">Structs</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="Structs/SocketIOClientConfiguration.html">SocketIOClientConfiguration</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="Typealiases.html">Typealiases</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="Typealiases.html#/s:8SocketIO11AckCallback">AckCallback</a>
</li>
<li class="nav-group-task">
<a class="nav-group-task-link" href="Typealiases.html#/s:8SocketIO14NormalCallback">NormalCallback</a>
</li>
</ul>
</li>
</ul>
</nav>
<article class="main-content">
<section class="section">
<div class="section-content">
<p><a href="https://travis-ci.org/socketio/socket.io-client-swift"><img src="https://travis-ci.org/socketio/socket.io-client-swift.svg?branch=master" alt="Build Status"></a></p>
<h1 id='socket-io-client-swift' class='heading'>Socket.IO-Client-Swift</h1>
<p>Socket.IO-client for iOS/OS X.</p>
<h2 id='example' class='heading'>Example</h2>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">SocketIO</span>
<span class="k">let</span> <span class="nv">socket</span> <span class="o">=</span> <span class="kt">SocketIOClient</span><span class="p">(</span><span class="nv">socketURL</span><span class="p">:</span> <span class="kt">URL</span><span class="p">(</span><span class="nv">string</span><span class="p">:</span> <span class="s">"http://localhost:8080"</span><span class="p">)</span><span class="o">!</span><span class="p">,</span> <span class="nv">config</span><span class="p">:</span> <span class="p">[</span><span class="o">.</span><span class="nf">log</span><span class="p">(</span><span class="kc">true</span><span class="p">),</span> <span class="o">.</span><span class="nf">forcePolling</span><span class="p">(</span><span class="kc">true</span><span class="p">)])</span>
<span class="n">socket</span><span class="o">.</span><span class="nf">on</span><span class="p">(</span><span class="s">"connect"</span><span class="p">)</span> <span class="p">{</span><span class="n">data</span><span class="p">,</span> <span class="n">ack</span> <span class="k">in</span>
<span class="nf">print</span><span class="p">(</span><span class="s">"socket connected"</span><span class="p">)</span>
<span class="p">}</span>
<span class="n">socket</span><span class="o">.</span><span class="nf">on</span><span class="p">(</span><span class="s">"currentAmount"</span><span class="p">)</span> <span class="p">{</span><span class="n">data</span><span class="p">,</span> <span class="n">ack</span> <span class="k">in</span>
<span class="k">if</span> <span class="k">let</span> <span class="nv">cur</span> <span class="o">=</span> <span class="n">data</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">as?</span> <span class="kt">Double</span> <span class="p">{</span>
<span class="n">socket</span><span class="o">.</span><span class="nf">emitWithAck</span><span class="p">(</span><span class="s">"canUpdate"</span><span class="p">,</span> <span class="n">cur</span><span class="p">)</span><span class="o">.</span><span class="nf">timingOut</span><span class="p">(</span><span class="nv">after</span><span class="p">:</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span><span class="n">data</span> <span class="k">in</span>
<span class="n">socket</span><span class="o">.</span><span class="nf">emit</span><span class="p">(</span><span class="s">"update"</span><span class="p">,</span> <span class="p">[</span><span class="s">"amount"</span><span class="p">:</span> <span class="n">cur</span> <span class="o">+</span> <span class="mf">2.50</span><span class="p">])</span>
<span class="p">}</span>
<span class="n">ack</span><span class="o">.</span><span class="nf">with</span><span class="p">(</span><span class="s">"Got your currentAmount"</span><span class="p">,</span> <span class="s">"dude"</span><span class="p">)</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="n">socket</span><span class="o">.</span><span class="nf">connect</span><span class="p">()</span>
</code></pre>
<h2 id='objective-c-example' class='heading'>Objective-C Example</h2>
<pre class="highlight plaintext"><code>@import SocketIO;
NSURL* url = [[NSURL alloc] initWithString:@"http://localhost:8080"];
SocketIOClient* socket = [[SocketIOClient alloc] initWithSocketURL:url config:@{@"log": @YES, @"forcePolling": @YES}];
[socket on:@"connect" callback:^(NSArray* data, SocketAckEmitter* ack) {
NSLog(@"socket connected");
}];
[socket on:@"currentAmount" callback:^(NSArray* data, SocketAckEmitter* ack) {
double cur = [[data objectAtIndex:0] floatValue];
[[socket emitWithAck:@"canUpdate" with:@[@(cur)]] timingOutAfter:0 callback:^(NSArray* data) {
[socket emit:@"update" withItems:@[@{@"amount": @(cur + 2.50)}]];
}];
[ack with:@[@"Got your currentAmount, ", @"dude"]];
}];
[socket connect];
</code></pre>
<h2 id='features' class='heading'>Features</h2>
<ul>
<li>Supports socket.io 1.0+</li>
<li>Supports binary</li>
<li>Supports Polling and WebSockets</li>
<li>Supports TLS/SSL</li>
<li>Can be used from Objective-C</li>
</ul>
<h2 id='installation' class='heading'>Installation</h2>
<p>Requires Swift 3/Xcode 8.x</p>
<p>If you need swift 2.3 use the swift2.3 tag (Pre-Swift 3 support is no longer maintained)</p>
<p>If you need swift 2.2 use 7.x (Pre-Swift 3 support is no longer maintained)</p>
<p>If you need Swift 2.1 use v5.5.0 (Pre-Swift 2.2 support is no longer maintained)</p>
<p>If you need Swift 1.2 use v2.4.5 (Pre-Swift 2 support is no longer maintained)</p>
<p>If you need Swift 1.1 use v1.5.2. (Pre-Swift 1.2 support is no longer maintained)</p>
<h3 id='manually-ios-7' class='heading'>Manually (iOS 7+)</h3>
<ol>
<li>Copy the Source folder into your Xcode project. (Make sure you add the files to your target(s))</li>
<li>If you plan on using this from Objective-C, read <a href="https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html">this</a> on exposing Swift code to Objective-C.</li>
</ol>
<h3 id='swift-package-manager' class='heading'>Swift Package Manager</h3>
<p>Add the project as a dependency to your Package.swift:</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">PackageDescription</span>
<span class="k">let</span> <span class="nv">package</span> <span class="o">=</span> <span class="kt">Package</span><span class="p">(</span>
<span class="nv">name</span><span class="p">:</span> <span class="s">"YourSocketIOProject"</span><span class="p">,</span>
<span class="nv">dependencies</span><span class="p">:</span> <span class="p">[</span>
<span class="o">.</span><span class="kt">Package</span><span class="p">(</span><span class="nv">url</span><span class="p">:</span> <span class="s">"https://github.com/socketio/socket.io-client-swift"</span><span class="p">,</span> <span class="nv">majorVersion</span><span class="p">:</span> <span class="mi">8</span><span class="p">)</span>
<span class="p">]</span>
<span class="p">)</span>
</code></pre>
<p>Then import <code>import SocketIO</code>.</p>
<h3 id='carthage' class='heading'>Carthage</h3>
<p>Add this line to your <code>Cartfile</code>:</p>
<pre class="highlight plaintext"><code>github "socketio/socket.io-client-swift" ~&gt; 8.3.3 # Or latest version
</code></pre>
<p>Run <code>carthage update --platform ios,macosx</code>.</p>
<h3 id='cocoapods-1-0-0-or-later' class='heading'>CocoaPods 1.0.0 or later</h3>
<p>Create <code>Podfile</code> and add <code>pod &#39;Socket.IO-Client-Swift&#39;</code>:</p>
<pre class="highlight ruby"><code><span class="n">use_frameworks!</span>
<span class="n">target</span> <span class="s1">'YourApp'</span> <span class="k">do</span>
<span class="n">pod</span> <span class="s1">'Socket.IO-Client-Swift'</span><span class="p">,</span> <span class="s1">'~&gt; 8.3.3'</span> <span class="c1"># Or latest version</span>
<span class="k">end</span>
</code></pre>
<p>Install pods:</p>
<pre class="highlight plaintext"><code>$ pod install
</code></pre>
<p>Import the module:</p>
<p>Swift:</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">SocketIO</span>
</code></pre>
<p>Objective-C:</p>
<pre class="highlight plaintext"><code>@import SocketIO;
</code></pre>
<h3 id='cocoaseeds' class='heading'>CocoaSeeds</h3>
<p>Add this line to your <code>Seedfile</code>:</p>
<pre class="highlight plaintext"><code>github "socketio/socket.io-client-swift", "v8.3.3", :files =&gt; "Source/*.swift" # Or latest version
</code></pre>
<p>Run <code>seed install</code>.</p>
<h1 id='api' class='heading'>API</h1>
<h2 id='constructors' class='heading'>Constructors</h2>
<p><code>init(var socketURL: NSURL, config: SocketIOClientConfiguration = [])</code> - Creates a new SocketIOClient. If your socket.io server is secure, you need to specify <code>https</code> in your socketURL.</p>
<p><code>convenience init(socketURL: NSURL, options: NSDictionary?)</code> - Same as above, but meant for Objective-C. See Options on how convert between SocketIOClientOptions and dictionary keys.</p>
<h3 id='options' class='heading'>Options</h3>
<p>All options are a case of SocketIOClientOption. To get the Objective-C Option, convert the name to lowerCamelCase.</p>
<pre class="highlight swift"><code><span class="k">case</span> <span class="nf">connectParams</span><span class="p">([</span><span class="kt">String</span><span class="p">:</span> <span class="kt">AnyObject</span><span class="p">])</span> <span class="c1">// Dictionary whose contents will be passed with the connection.</span>
<span class="k">case</span> <span class="nf">cookies</span><span class="p">([</span><span class="kt">NSHTTPCookie</span><span class="p">])</span> <span class="c1">// An array of NSHTTPCookies. Passed during the handshake. Default is nil.</span>
<span class="k">case</span> <span class="nf">doubleEncodeUTF8</span><span class="p">(</span><span class="kt">Bool</span><span class="p">)</span> <span class="c1">// Whether or not to double encode utf8. If using the node based server this should be true. Default is true.</span>
<span class="k">case</span> <span class="nf">extraHeaders</span><span class="p">([</span><span class="kt">String</span><span class="p">:</span> <span class="kt">String</span><span class="p">])</span> <span class="c1">// Adds custom headers to the initial request. Default is nil.</span>
<span class="k">case</span> <span class="nf">forcePolling</span><span class="p">(</span><span class="kt">Bool</span><span class="p">)</span> <span class="c1">// `true` forces the client to use xhr-polling. Default is `false`</span>
<span class="k">case</span> <span class="nf">forceNew</span><span class="p">(</span><span class="kt">Bool</span><span class="p">)</span> <span class="c1">// Will a create a new engine for each connect. Useful if you find a bug in the engine related to reconnects</span>
<span class="k">case</span> <span class="nf">forceWebsockets</span><span class="p">(</span><span class="kt">Bool</span><span class="p">)</span> <span class="c1">// `true` forces the client to use WebSockets. Default is `false`</span>
<span class="k">case</span> <span class="nf">handleQueue</span><span class="p">(</span><span class="n">dispatch_queue_t</span><span class="p">)</span> <span class="c1">// The dispatch queue that handlers are run on. Default is the main queue.</span>
<span class="k">case</span> <span class="nf">log</span><span class="p">(</span><span class="kt">Bool</span><span class="p">)</span> <span class="c1">// If `true` socket will log debug messages. Default is false.</span>
<span class="k">case</span> <span class="nf">logger</span><span class="p">(</span><span class="kt">SocketLogger</span><span class="p">)</span> <span class="c1">// Custom logger that conforms to SocketLogger. Will use the default logging otherwise.</span>
<span class="k">case</span> <span class="nf">nsp</span><span class="p">(</span><span class="kt">String</span><span class="p">)</span> <span class="c1">// The namespace to connect to. Must begin with /. Default is `/`</span>
<span class="k">case</span> <span class="nf">path</span><span class="p">(</span><span class="kt">String</span><span class="p">)</span> <span class="c1">// If the server uses a custom path. ex: `"/swift/"`. Default is `""`</span>
<span class="k">case</span> <span class="nf">reconnects</span><span class="p">(</span><span class="kt">Bool</span><span class="p">)</span> <span class="c1">// Whether to reconnect on server lose. Default is `true`</span>
<span class="k">case</span> <span class="nf">reconnectAttempts</span><span class="p">(</span><span class="kt">Int</span><span class="p">)</span> <span class="c1">// How many times to reconnect. Default is `-1` (infinite tries)</span>
<span class="k">case</span> <span class="nf">reconnectWait</span><span class="p">(</span><span class="kt">Int</span><span class="p">)</span> <span class="c1">// Amount of time to wait between reconnects. Default is `10`</span>
<span class="k">case</span> <span class="nf">sessionDelegate</span><span class="p">(</span><span class="kt">NSURLSessionDelegate</span><span class="p">)</span> <span class="c1">// Sets an NSURLSessionDelegate for the underlying engine. Useful if you need to handle self-signed certs. Default is nil.</span>
<span class="k">case</span> <span class="nf">secure</span><span class="p">(</span><span class="kt">Bool</span><span class="p">)</span> <span class="c1">// If the connection should use TLS. Default is false.</span>
<span class="k">case</span> <span class="nf">security</span><span class="p">(</span><span class="kt">SSLSecurity</span><span class="p">)</span> <span class="c1">// Allows you to set which certs are valid. Useful for SSL pinning.</span>
<span class="k">case</span> <span class="nf">selfSigned</span><span class="p">(</span><span class="kt">Bool</span><span class="p">)</span> <span class="c1">// Sets WebSocket.selfSignedSSL. Use this if you're using self-signed certs.</span>
<span class="k">case</span> <span class="nf">voipEnabled</span><span class="p">(</span><span class="kt">Bool</span><span class="p">)</span> <span class="c1">// Only use this option if you're using the client with VoIP services. Changes the way the WebSocket is created. Default is false</span>
</code></pre>
<h3 id='methods' class='heading'>Methods</h3>
<ol>
<li><code>on(_ event: String, callback: NormalCallback) -&gt; NSUUID</code> - Adds a handler for an event. Items are passed by an array. <code>ack</code> can be used to send an ack when one is requested. See example. Returns a unique id for the handler.</li>
<li><code>once(_ event: String, callback: NormalCallback) -&gt; NSUUID</code> - Adds a handler that will only be executed once. Returns a unique id for the handler.</li>
<li><code>onAny(callback:((event: String, items: AnyObject?)) -&gt; Void)</code> - Adds a handler for all events. It will be called on any received event.</li>
<li><code>emit(_ event: String, _ items: AnyObject...)</code> - Sends a message. Can send multiple items.</li>
<li><code>emit(_ event: String, withItems items: [AnyObject])</code> - <code>emit</code> for Objective-C</li>
<li><code>emitWithAck(_ event: String, _ items: AnyObject...) -&gt; OnAckCallback</code> - Sends a message that requests an acknowledgement from the server. Returns an object which you can use to add a handler. See example. Note: The message is not sent until you call timingOut(after:) on the returned object.</li>
<li><code>emitWithAck(_ event: String, withItems items: [AnyObject]) -&gt; OnAckCallback</code> - <code>emitWithAck</code> for Objective-C. Note: The message is not sent until you call timingOutAfter on the returned object.</li>
<li><code>connect()</code> - Establishes a connection to the server. A <q>connect</q> event is fired upon successful connection.</li>
<li><code>connect(timeoutAfter timeoutAfter: Int, withTimeoutHandler handler: (() -&gt; Void)?)</code> - Connect to the server. If it isn&rsquo;t connected after timeoutAfter seconds, the handler is called.</li>
<li><code>disconnect()</code> - Closes the socket. Reopening a disconnected socket is not fully tested.</li>
<li><code>reconnect()</code> - Causes the client to reconnect to the server.</li>
<li><code>joinNamespace(_ namespace: String)</code> - Causes the client to join namespace. Shouldn&rsquo;t need to be called unless you change namespaces manually.</li>
<li><code>leaveNamespace()</code> - Causes the client to leave the nsp and go back to /</li>
<li><code>off(_ event: String)</code> - Removes all event handlers for event.</li>
<li><code>off(id id: NSUUID)</code> - Removes the event that corresponds to id.</li>
<li><code>removeAllHandlers()</code> - Removes all handlers.</li>
</ol>
<h3 id='client-events' class='heading'>Client Events</h3>
<ol>
<li><code>connect</code> - Emitted when on a successful connection.</li>
<li><code>disconnect</code> - Emitted when the connection is closed.</li>
<li><code>error</code> - Emitted on an error.</li>
<li><code>reconnect</code> - Emitted when the connection is starting to reconnect.</li>
<li><code>reconnectAttempt</code> - Emitted when attempting to reconnect.</li>
</ol>
<h2 id='detailed-example' class='heading'>Detailed Example</h2>
<p>A more detailed example can be found <a href="https://github.com/nuclearace/socket.io-client-swift-example">here</a></p>
<p>An example using the Swift Package Manager can be found <a href="https://github.com/nuclearace/socket.io-client-swift-spm-example">here</a></p>
<h2 id='license' class='heading'>License</h2>
<p>MIT</p>
</div>
</section>
</article>
</div>
<section class="footer">
<p>&copy; 2017 <a class="link" href="https://github.com/socketio/socket.io-client-swift" target="_blank" rel="external">Erik</a>. All rights reserved. (Last updated: 2017-05-06)</p>
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.8.1</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
</section>
</body>
</div>
</html>