SRConnection Class Reference

Inherits from	NSObject
Declared in	SRConnection.h

Overview

An SRConnection object provides support to open a persistent connection with a SignalR Server.

SRConnection’s delegate methods—defined by the SRConnectionDelegate protocol allows an object to receive informational callbacks when events occur on the SRConnection object

Tasks

Properties

started
A block to be called when the connection’s underlying transport is initialized the first time
property
received
A block to be called when the connection’s underlying transport receives new data
property
error
A block to be called when the connection’s underlying transport receives a error
property
closed
A block to be called when the connection’s underlying transport is closed
property
reconnected
A block to be called when the connection’s underlying transport is reconnected
property
credentials
The authentication credential to be applied to each request Support is limited to HTTP Basic Authentication
property
groups
A NSMutableArray of the connected groups
property
sending
A block to be called prior to sending data
property
url
The endpoint at which the connection is initialized to
property
active
A BOOL representing the status of the connection when TRUE the connection has been started
property
messageId
An NSNumber representing the current message id
property
connectionId
An NSString representing the current connectionId established during negotiation
property
items
An NSMutableDictionary containing objects that need to be persisted by the underlying transport for example the last httprequest.
property
queryString
An NSString representing the custom query string to be applied to each request
property
initialized
A BOOL representing the status of the connection underlying transport when TRUE the connection’s underlying transport has been started
property
headers
An NSMutableDictionary representing the headers to be applied to each request
property
delegate
The object that acts as the delegate of the receiving SRConnection.
property

Initializing an SRConnection Object

+ connectionWithURL:
A convenience method for initWithURL:(NSString *)url;
+ connectionWithURL:query:
A convenience method for initWithURL:(NSString )url query:(NSDictionary )queryString;
+ connectionWithURL:queryString:
A convenience method for initWithURL:(NSString )url queryString:(NSString )queryString;;
– initWithURL:
Initializes a new SRConnection object at the specified URL
– initWithURL:query:
Initializes a new SRConnection object at the specified URL
– initWithURL:queryString:
Initializes a new SRConnection object at the specified URL

Connection Management

– start
Starts the connection using SRAutoTransport
– start:
Starts the connection
– negotiate
Perfromed prior to starting the underlying transport, a negoitate establishes the initial connection with the server by making a request to url/negotiate a sucessful response returns an SRNegotiationResponse object which establishes the connectionId at which time the underlying transport will be started. dispatches the opened event to either the SRConnectionDelegate by calling [self.delegate SRConnectionDidOpen:self]; or to the self.started callback once the transport is successfully initialized
– stop
Stops the connection dispatches the closed event to either the SRConnectionDelegate by calling [self.delegate SRConnectionDidClose:self]; or to the self.closed callback sets active and initialized to NO

Sending Data

– send:
Sends data over the connection. calls [self send:message continueWith:nil];
– send:continueWith:
Sends data over the connection.

Receiving Data

– didReceiveData:
Called when the connection receives new data dispatches the response to either the SRConnectionDelegate by calling [self.delegate SRConnection:self didReceiveData:message]; or to the self.received callback
– didReceiveError:
Called when the connection receives an error dispatches the error to either the SRConnectionDelegate by calling [self.delegate SRConnection:self didReceiveError:ex]; or to the self.error callback
– didReconnect
Called when the connection reconnects after a server side timeout dispatches the reconnect to either the SRConnectionDelegate by calling [self.delegate SRConnectionDidReconnect:self]; or to the self.reconnected callback

Preparing Requests

– addValue:forHTTPHeaderField:
Adds an HTTP header to the receiver’s HTTP header dictionary.
– prepareRequest:
Sets the user agent, crediential information and other relevant header values on each connection
– createUserAgentString:
Generates the client UserAgent header field

Extensions Methods

– getValue:
An extension method for accessing objects belonging to [SRConnection items]

Properties

active

A BOOL representing the status of the connection when TRUE the connection has been started

@property (assign, nonatomic, readonly, getter=isActive) BOOL active

Declared In

SRConnection.h

closed

A block to be called when the connection’s underlying transport is closed

@property (copy) onClosed closed

Declared In

SRConnection.h

connectionId

An NSString representing the current connectionId established during negotiation

@property (strong, nonatomic, readwrite) NSString *connectionId

Declared In

SRConnection.h

credentials

The authentication credential to be applied to each request Support is limited to HTTP Basic Authentication

@property (strong, nonatomic, readwrite) NSURLCredential *credentials

Declared In

SRConnection.h

delegate

The object that acts as the delegate of the receiving SRConnection.

@property (nonatomic, assign) id<> delegate

Declared In

SRConnection.h

error

A block to be called when the connection’s underlying transport receives a error

@property (copy) onError error

Declared In

SRConnection.h

groups

A NSMutableArray of the connected groups

@property (strong, nonatomic, readwrite) NSMutableArray *groups

Declared In

SRConnection.h

headers

An NSMutableDictionary representing the headers to be applied to each request

@property (strong, nonatomic, readonly) NSMutableDictionary *headers

Declared In

SRConnection.h

initialized

A BOOL representing the status of the connection underlying transport when TRUE the connection’s underlying transport has been started

@property (assign, nonatomic, readonly) BOOL initialized

Declared In

SRConnection.h

items

An NSMutableDictionary containing objects that need to be persisted by the underlying transport for example the last httprequest.

@property (strong, nonatomic, readwrite) NSMutableDictionary *items

Declared In

SRConnection.h

messageId

An NSNumber representing the current message id

@property (strong, nonatomic, readwrite) NSNumber *messageId

Declared In

SRConnection.h

queryString

An NSString representing the custom query string to be applied to each request

@property (strong, nonatomic, readonly) NSString *queryString

Declared In

SRConnection.h

received

A block to be called when the connection’s underlying transport receives new data

@property (copy) onReceived received

Declared In

SRConnection.h

reconnected

A block to be called when the connection’s underlying transport is reconnected

@property (copy) onReconnected reconnected

Declared In

SRConnection.h

sending

A block to be called prior to sending data

@property (copy) onSending sending

Declared In

SRConnection.h

started

A block to be called when the connection’s underlying transport is initialized the first time

@property (copy) onStarted started

Declared In

SRConnection.h

url

The endpoint at which the connection is initialized to

@property (strong, nonatomic, readwrite) NSString *url

Declared In

SRConnection.h

Class Methods

connectionWithURL:

A convenience method for initWithURL:(NSString *)url;

+ (SRConnection *)connectionWithURL:(NSString *)URL

Parameters

URL: the endpoint to initialize the new connection to

Return Value

an SRConnection object

Discussion

SRConnection *connection = [SRConnection connectionWithURL:@“http://mysite/echo”]http://mysite/echo“];

Declared In

SRConnection.h

connectionWithURL:query:

A convenience method for initWithURL:(NSString )url query:(NSDictionary )queryString;

+ (SRConnection *)connectionWithURL:(NSString *)url query:(NSDictionary *)queryString

Parameters

url: the endpoint to initialize the new connection to

queryString: an NSDictionary representation of a custom query string to be appended to the SRConnection endpoint

Return Value

an SRConnection object

Discussion

SRConnection *connection = [SRConnection connectionWithURL:@“http://mysite/echo”]http://mysite/echo“];

Declared In

SRConnection.h

connectionWithURL:queryString:

A convenience method for initWithURL:(NSString )url queryString:(NSString )queryString;;

+ (SRConnection *)connectionWithURL:(NSString *)url queryString:(NSString *)queryString

Parameters

url: the endpoint to initialize the new connection to

queryString: an NSString representation of a custom query string to be appended to the SRConnection endpoint

Return Value

an SRConnection object

Discussion

Important Url cannot contain a QueryString directly. Namely the string should not contain the prefix ‘?’ It is recommended that (SRConnection )connectionWithURL:(NSString )url query:(NSDictionary *)queryString; is used instead

Declared In

SRConnection.h

Instance Methods

addValue:forHTTPHeaderField:

Adds an HTTP header to the receiver’s HTTP header dictionary.

- (void)addValue:(NSString *)value forHTTPHeaderField:(NSString *)field

Parameters

value: The value for the header field.

field: the name of the header field.

Declared In

SRConnection.h

createUserAgentString:

Generates the client UserAgent header field

- (NSString *)createUserAgentString:(NSString *)client

Parameters

client: the client name

Return Value

The user agent will be of the form client/version (DeviceModel/DeviceVersion)

Declared In

SRConnection.h

didReceiveData:

Called when the connection receives new data dispatches the response to either the SRConnectionDelegate by calling [self.delegate SRConnection:self didReceiveData:message]; or to the self.received callback

- (void)didReceiveData:(NSString *)data

Parameters

data: the data received from the server

Declared In

SRConnection.h

didReceiveError:

Called when the connection receives an error dispatches the error to either the SRConnectionDelegate by calling [self.delegate SRConnection:self didReceiveError:ex]; or to the self.error callback

- (void)didReceiveError:(NSError *)ex

Parameters

ex: the error received from the server

Declared In

SRConnection.h

didReconnect

Called when the connection reconnects after a server side timeout dispatches the reconnect to either the SRConnectionDelegate by calling [self.delegate SRConnectionDidReconnect:self]; or to the self.reconnected callback

- (void)didReconnect

Declared In

SRConnection.h

getValue:

An extension method for accessing objects belonging to [SRConnection items]

- (id)getValue:(NSString *)key

Parameters

key: he key for which to return the corresponding value.

Return Value

Returns the value associated with a given key.

Declared In

SRConnectionExtensions.h

initWithURL:

Initializes a new SRConnection object at the specified URL

- (id)initWithURL:(NSString *)url

Parameters

url: the endpoint to initialize the new connection to

Return Value

an SRConnection object

Discussion

SRConnection *connection = [[SRConnection alloc] initWithURL:@“http://mysite/echo”];

Declared In

SRConnection.h

initWithURL:query:

Initializes a new SRConnection object at the specified URL

- (id)initWithURL:(NSString *)url query:(NSDictionary *)queryString

Parameters

url: the endpoint to initialize the new connection to

queryString: an NSDictionary representation of a custom query string to be appended to the SRConnection endpoint

Return Value

an SRConnection object

Declared In

SRConnection.h

initWithURL:queryString:

Initializes a new SRConnection object at the specified URL

- (id)initWithURL:(NSString *)url queryString:(NSString *)queryString

Parameters

url: the endpoint to initialize the new connection to

queryString: an NSString representation of a custom query string to be appended to the SRConnection endpoint

Return Value

an SRConnection object

Discussion

Important Url cannot contain a QueryString directly. Namely the string should not contain the prefix ‘?’ It is recommended that (id)initWithURL:(NSString )url query:(NSDictionary )queryString;; is used instead

Declared In

SRConnection.h

negotiate

Perfromed prior to starting the underlying transport, a negoitate establishes the initial connection with the server by making a request to url/negotiate a sucessful response returns an SRNegotiationResponse object which establishes the connectionId at which time the underlying transport will be started. dispatches the opened event to either the SRConnectionDelegate by calling [self.delegate SRConnectionDidOpen:self]; or to the self.started callback once the transport is successfully initialized

- (void)negotiate

Declared In

SRConnection.h

prepareRequest:

Sets the user agent, crediential information and other relevant header values on each connection

- (void)prepareRequest:(id)request

Parameters

request: The NSMutableURLRequest that will be sent to the server

Declared In

SRConnection.h

send:

Sends data over the connection. calls [self send:message continueWith:nil];

- (void)send:(NSString *)message

Parameters

message: the message to send

Declared In

SRConnection.h

send:continueWith:

Sends data over the connection.

- (void)send:(NSString *)message continueWith:(void ( ^ ) ( id response ))block

Parameters

message: the message to send

block: the callback to be called once the message is sent.

Discussion

Important Start must be called before sending data

Declared In

SRConnection.h

start

Starts the connection using SRAutoTransport

- (void)start

Discussion

sets active to YES

Declared In

SRConnection.h

start:

Starts the connection

- (void)start:(id<SRClientTransport>)transport

Parameters

transport: the transport to use for the connection

Discussion

sets active to YES

Declared In

SRConnection.h

stop

Stops the connection dispatches the closed event to either the SRConnectionDelegate by calling [self.delegate SRConnectionDidClose:self]; or to the self.closed callback sets active and initialized to NO

- (void)stop

Declared In

SRConnection.h