Inherits from NSObject
Declared in KGWebSocket.h

Overview

The KGWebSocket provides the API for creating and managing a WebSocket connection, as well as sending and receiving data on the connection.

Refer to http://www.w3.org/TR/websockets/ for the published standard W3C WebSocket API specification.

KGWebSocket’s delegate methods – defined by KGWebSocketDelegate protocol allows an object to define callbacks for events such as connection opened, message received, connection closed, error occured. The callbacks for such events can also be provided as blocks using block properties.

Tasks

  • – url

    The NSURL that refers to the server location.

  • – readyState

    The current state of the connection. The value can be one of 0(CONNECTING), 1(OPEN), 2(CLOSING), 3(CLOSED).

  • – negotiatedProtocol

    A string indicating the name of the sub-protocol the server selected. this will be one of the strings specified in the protocols parameter when creating the WebSocket object.

  • – enabledProtocols

    Gets the names of all the protocols that are enabled for this connection. Returns an empty array if protocols are not enabled.

  • – setEnabledProtocols:

    Registers the protocols to be negotiated with the server during the handshake. This method must be invoked before method connect is called. If this method is invoked after a connection has been successfully established, an exception is thrown.

  • – negotiatedExtensions

    Gets names of all the enabled extensions that have been successfully negotiated between the client and the server during the initial handshake.

  • – enabledExtensions

    Gets the names of all the extensions that have been enabled for this connection. The enabled extensions are negotiated between the client and the server during the handshake. The names of the negotiated extensions can be obtained using method negotiatedExtensions. An empty array is returned if no extensions have been enabled for this connection.

  • – setEnabledExtensions:

    Registers the names of all the extensions that must be negotiated between the client and the server during the handshake. This method must be invoked before invoking the method connect.

  • – enabledParameter:

    Gets the value of the specified KGWebSocketExtensionParameter defined in an enabled extension. If the parameter is not defined for this connection but a default value for the parameter is set using the method [KGWebSocketFactory setDefaultParameter:value:], then the default value is returned.

  • – negotiatedParameter:

    Returns the value of the specified KGWebSocketExtensionParameter of a negotiated extension.

  • – setEnabledParameter:value:

    Sets the value of the specified KGWebSocketExtensionParameter defined in an enabled extension. The application developer should set the extension parameters of the enabled extensions before invoking the connect method.

  • – connect

    Establishes the websocket connection to the server. It uses server url specified when creating this instance using KGWebSocketFactory.

  • – close

    Closes the WebSocket connection or connection attempt, if any. If the connection is already closed, this method does nothing.

  • – close:

    Closes the WebSocket connection or connection attempt, if any with the code specified. If the connection is already closed, this method does nothing.

  • – close:reason:

    Closes the WebSocket connection or connection attempt, if any with the code and reason specified. If the connection is already closed, this method does nothing.

  • – send:

    Transmits data to the server over the WebSocket connection.

  • – delegate

    Returns the delegate set for the receiver.

  • – setDelegate:

    Sets the delegate for the receiver.

  • – challengeHandler

    Gets the KGChallengeHandler that is used during authentication both at the connect-time as well as at subsequent revalidation-time that occurs at regular intervals.

  • – setChallengeHandler:

    Sets the KGChallengeHandler that is used during authentication both at the connect-time as well as at subsequent revalidation-time that occurs at regular intervals.

  • – clientIdentity

    Returns the SecIdentityRef object used for client certificate authentication

  • – setClientIdentity:

    Sets Client Identity for SSL client certificate authentication.

  • – connectTimeout

    Gets the connect timeout in milliseconds. The timeout will expire if there is no exchange of packets(for example, 100% packet loss) while establishing the connection. A timeout value of zero indicates no timeout. Default connect timeout is zero.

  • – setConnectTimeout:

    Sets the connect timeout in milliseconds. The timeout will expire if there is no exchange of packets(for example, 100% packet loss) while establishing the connection. A timeout value of zero indicates no timeout.

  •   didOpen

    The block to execute when WebSocket connection’s readyState changes to OPEN. This indicates that the connection is ready to send and receive data.

    property
  •   didClose

    The block to execute when the connection is closed. The block takes the following arguments:
    websocket – The KGWebSocket instance that is closed
    code – The WebSocket connection close code provided by the server
    reason – A string indicating the reason the connection is closed
    wasClean – Indicates whether or not the connection was cleanly closed.

    property
  •   didReceiveError

    The block to execute when an error occurs.

    property
  •   didReceiveMessage

    The block to execute when a message is received from the server. The data ‘is’ either UTF8-String (type: NSString) or binary (type: NSData)

    property

Properties

didClose

The block to execute when the connection is closed. The block takes the following arguments:
websocket – The KGWebSocket instance that is closed
code – The WebSocket connection close code provided by the server
reason – A string indicating the reason the connection is closed
wasClean – Indicates whether or not the connection was cleanly closed.

@property (copy) void ( ^ ) ( KGWebSocket *websocket , NSInteger code , NSString *reason , BOOL wasClean ) didClose

Declared In

KGWebSocket.h

didOpen

The block to execute when WebSocket connection’s readyState changes to OPEN. This indicates that the connection is ready to send and receive data.

@property (copy) void ( ^ ) ( KGWebSocket *websocket ) didOpen

Declared In

KGWebSocket.h

didReceiveError

The block to execute when an error occurs.

@property (copy) void ( ^ ) ( KGWebSocket *websocket , NSError *error ) didReceiveError

Declared In

KGWebSocket.h

didReceiveMessage

The block to execute when a message is received from the server. The data ‘is’ either UTF8-String (type: NSString) or binary (type: NSData)

@property (copy) void ( ^ ) ( KGWebSocket *websocket , id data ) didReceiveMessage

Declared In

KGWebSocket.h

Instance Methods

challengeHandler

Gets the KGChallengeHandler that is used during authentication both at the connect-time as well as at subsequent revalidation-time that occurs at regular intervals.

- (KGChallengeHandler *)challengeHandler

Declared In

KGWebSocket.h

clientIdentity

Returns the SecIdentityRef object used for client certificate authentication

- (SecIdentityRef)clientIdentity

Return Value

SecIdentityRef object

Declared In

KGWebSocket.h

close

Closes the WebSocket connection or connection attempt, if any. If the connection is already closed, this method does nothing.

- (void)close

Declared In

KGWebSocket.h

close:

Closes the WebSocket connection or connection attempt, if any with the code specified. If the connection is already closed, this method does nothing.

- (void)close:(NSInteger)code

Parameters

code

A numeric value indicating the status code explaining why the connection is being closed. It must equal to 1000 or in range 3000 to 4999.

Exceptions

NSException

If code and/or reason is invalid.

Declared In

KGWebSocket.h

close:reason:

Closes the WebSocket connection or connection attempt, if any with the code and reason specified. If the connection is already closed, this method does nothing.

- (void)close:(NSInteger)code reason:(NSString *)reason

Parameters

code

A numeric value indicating the status code explaining why the connection is being closed. It must equal to 1000 or in range 3000 to 4999.

reason

A human-readable string explaining why the connection is closing. This string must be no longer than 123 bytes of UTF-8 text (not characters).

Exceptions

NSException

If code and/or reason is invalid.

Declared In

KGWebSocket.h

connect

Establishes the websocket connection to the server. It uses server url specified when creating this instance using KGWebSocketFactory.

- (void)connect

Declared In

KGWebSocket.h

connectTimeout

Gets the connect timeout in milliseconds. The timeout will expire if there is no exchange of packets(for example, 100% packet loss) while establishing the connection. A timeout value of zero indicates no timeout. Default connect timeout is zero.

- (int)connectTimeout

Return Value

connect timeout value in milliseconds

Declared In

KGWebSocket.h

delegate

Returns the delegate set for the receiver.

- (id<KGWebSocketDelegate>)delegate

Declared In

KGWebSocket.h

enabledExtensions

Gets the names of all the extensions that have been enabled for this connection. The enabled extensions are negotiated between the client and the server during the handshake. The names of the negotiated extensions can be obtained using method negotiatedExtensions. An empty array is returned if no extensions have been enabled for this connection.

- (NSArray *)enabledExtensions

Declared In

KGWebSocket.h

enabledParameter:

Gets the value of the specified KGWebSocketExtensionParameter defined in an enabled extension. If the parameter is not defined for this connection but a default value for the parameter is set using the method [KGWebSocketFactory setDefaultParameter:value:], then the default value is returned.

- (id)enabledParameter:(KGWebSocketExtensionParameter *)parameter

Declared In

KGWebSocket.h

enabledProtocols

Gets the names of all the protocols that are enabled for this connection. Returns an empty array if protocols are not enabled.

- (NSArray *)enabledProtocols

Declared In

KGWebSocket.h

negotiatedExtensions

Gets names of all the enabled extensions that have been successfully negotiated between the client and the server during the initial handshake.

- (NSArray *)negotiatedExtensions

Discussion

Returns an empty array if no extensions were negotiated between the client and the server. The negotiated extensions will be a subset of the enabled extensions.

If this method is invoked before a connection is successfully established, exception is thrown.

Declared In

KGWebSocket.h

negotiatedParameter:

Returns the value of the specified KGWebSocketExtensionParameter of a negotiated extension.

- (id)negotiatedParameter:(KGWebSocketExtensionParameter *)parameter

Discussion

If this method is invoked before the connection is successfully established, an IllegalStateException is thrown.

Once the connection is closed, the negotiated parameters are cleared. Trying to retrieve the value will result in an IllegalStateException.

Declared In

KGWebSocket.h

negotiatedProtocol

A string indicating the name of the sub-protocol the server selected. this will be one of the strings specified in the protocols parameter when creating the WebSocket object.

- (NSString *)negotiatedProtocol

Declared In

KGWebSocket.h

readyState

The current state of the connection. The value can be one of 0(CONNECTING), 1(OPEN), 2(CLOSING), 3(CLOSED).

- (KGReadyState)readyState

Declared In

KGWebSocket.h

send:

Transmits data to the server over the WebSocket connection.

- (void)send:(id)data

Parameters

data

The data to send over WebSocket connection. It can either be NSString(for text message) or NSData(for binary message)

Exceptions

NSException

If data type is neither than NSData nor NSString

Declared In

KGWebSocket.h

setChallengeHandler:

Sets the KGChallengeHandler that is used during authentication both at the connect-time as well as at subsequent revalidation-time that occurs at regular intervals.

- (void)setChallengeHandler:(KGChallengeHandler *)challengeHandler

Parameters

challengeHandler

KGChallengeHandler used for authentication

Declared In

KGWebSocket.h

setClientIdentity:

Sets Client Identity for SSL client certificate authentication.

- (void)setClientIdentity:(SecIdentityRef)clientIdentity

Parameters

clientIdentity

SecIdentityRef for authentication

Declared In

KGWebSocket.h

setConnectTimeout:

Sets the connect timeout in milliseconds. The timeout will expire if there is no exchange of packets(for example, 100% packet loss) while establishing the connection. A timeout value of zero indicates no timeout.

- (void)setConnectTimeout:(int)connectTimeout

Parameters

connectTimeout

timeout value in milliseconds

Exceptions

NSException

if the connect timeout is being set after the connection has been established

NSException

if connectTimeout is negative

Declared In

KGWebSocket.h

setDelegate:

Sets the delegate for the receiver.

- (void)setDelegate:(id<KGWebSocketDelegate>)delegate

Parameters

delegate

The delegate for the receiver. The delegate must implement the KGWebSocketDelegate protocol.

Declared In

KGWebSocket.h

setEnabledExtensions:

Registers the names of all the extensions that must be negotiated between the client and the server during the handshake. This method must be invoked before invoking the method connect.

- (void)setEnabledExtensions:(NSArray *)extensions

Discussion

If this method is invoked after connection is successfully established, an exception is thrown.

NOTE: If the required parameter is missing for any of the enabled extensions, the KGWebSocket won’t be able to establish WebSocket connection and will throw exception on connect

Declared In

KGWebSocket.h

setEnabledParameter:value:

Sets the value of the specified KGWebSocketExtensionParameter defined in an enabled extension. The application developer should set the extension parameters of the enabled extensions before invoking the connect method.

- (void)setEnabledParameter:(KGWebSocketExtensionParameter *)parameter value:(id)value

Parameters

parameter

KGWebSocketExtensionParameter whose value needs to be set

value

value of the specified parameter

Discussion

Setting the parameter value when the connection is successfully established will result in an IllegalStateException.

If the parameter has a default value that was specified using [KGWebSocketFactory setDefaultParameter:value], then setting the same parameter using this method will override the default value.

Exceptions

NSException

if this method is invoked after WebSocket connection is established

NSException

if the type of the value is not the type specified in the KGWebSocketExtensionParameter

Declared In

KGWebSocket.h

setEnabledProtocols:

Registers the protocols to be negotiated with the server during the handshake. This method must be invoked before method connect is called. If this method is invoked after a connection has been successfully established, an exception is thrown.

- (void)setEnabledProtocols:(NSArray *)protocols

Declared In

KGWebSocket.h

url

The NSURL that refers to the server location.

- (NSURL *)url

Declared In

KGWebSocket.h