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
propertyinitialized
the first time -
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
propertyNSMutableArray
of the connected groups -
sending
A block to be called prior to sending data
property -
url
The endpoint at which the connection is initialized to
property -
active
A
propertyBOOL
representing the status of the connection when TRUE the connection has been started -
messageId
An
propertyNSNumber
representing the current message id -
connectionId
An
propertyNSString
representing the current connectionId established during negotiation -
items
An
propertyNSMutableDictionary
containing objects that need to be persisted by the underlying transport for example the last httprequest. -
queryString
An
propertyNSString
representing the custom query string to be applied to each request -
initialized
A
propertyBOOL
representing the status of the connection underlying transport when TRUE the connection’s underlying transport has been started -
headers
An
propertyNSMutableDictionary
representing the headers to be applied to each request -
delegate
The object that acts as the delegate of the receiving
propertySRConnection
.
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 setsactive
andinitialized
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 theSRConnection
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 theSRConnection
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
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 theSRConnection
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 theSRConnection
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