blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal
Public Member Functions | Properties

GDSocket Class Reference

TCP socket, supporting SSL/TLS and communication across the firewall. More...

#import <GDNETiOS.h>

List of all members.

Public Member Functions

Properties


Detailed Description

The BlackBerry Dynamics socket is for bi-directional data communication between the mobile application on the device and an application server. The application server can be on the Internet, or behind the enterprise firewall. Use of a Secure Socket Layer and Transport Layer Security (SSL/TLS) are supported.

The functions in this class cannot be called until BlackBerry Dynamics authorization processing is complete.

BlackBerry Dynamics secure communication does not go via the proxy specified in the device's native settings, if any.

See also:
GDiOS, for BlackBerry Dynamics authorization.
Thread support statement
Background Execution
GDHttpRequest
GDNetUtility
Manuals page for the BlackBerry Dynamics enterprise servers for the Platform Overview.

Overview

The BlackBerry Dynamics socket programming interface is asynchronous and state-based. The application attaches its own event-handler callbacks to the socket object. The callback functions are invoked when socket events occur, or when the socket changes state. Which functions can be called by the application at any time depend on the socket's state.

Callbacks are attached through a delegate class. The states in which each callback may be expected to be invoked are detailed in the delegate class's documentation, see GDSocketDelegate.

The availability of functions, and what actions take place, are detailed below, and summarized in the following table. The table also summarizes which callbacks may expect to be invoked in each state.

StateFunctions / Actions

Expected callbacks

Prepared Application can call connect: state becomes Connecting
Application can call disableHostVerification: no state change
Application can call disablePeerVerification: no state change

None

Connecting Open socket connection to server

onErr: no state change
onOpen: new state is Open

Open Application can call disconnect: state becomes Disconnecting
Application can call write: No state change

onRead: no state change
onErr: no state change
onClose: new state is Disconnected

Disconnecting Close socket connection

onRead: no state change
onErr: no state change
onClose: new state is Disconnected

Disconnected Application can call connect: state becomes Connecting

None

The transitions in the above table are also shown in the GDSocket state transition diagram

Sending and Receiving Data

Sending data through a BlackBerry Dynamics socket is a two-stage operation. The first stage is to add the data to the socket's outbound buffer. The socket's outbound buffer is represented by the writestream property, and is accessed using the BlackBerry Dynamics direct byte buffer interface. The second stage is to send the contents of the buffer through the socket connection. To send the buffer, call the write function.

Reading data from a BlackBerry Dynamics socket is asynchronous. When data is received at the device, the data is stored in the socket's inbound buffer. The application is then notified that data is available to read, by invocation of the delegate onRead callback. In the callback, the application consumes the received data from the inbound buffer. The inbound buffer is represented by the readStream property, and is accessed using the BlackBerry Dynamics direct byte buffer interface.

SSL/TLS Security

The BlackBerry Dynamics socket interface supports use of a Secure Socket Layer or Transport Layer Security (SSL/TLS) to send and receive data.

Using SSL/TLS requires that the remote end has a suitable certificate, and that the certificate is valid. A number of checks for validity are made by the BlackBerry Dynamics runtime, some of which can be switched off by the application.

A typical secure socket connection sequence would be as follows. The application makes a first connection attempt. In the first attempt, all checking is switched on. If a security error is encountered, this attempt will fail. The application can then switch off some checking, and make a second connection attempt to the same address as the first connection attempt. With less rigorous checking, the second attempt may succeed where the first failed.

The relevant parts of the API are:

Secure Protocol Selection

Establishing an SSL/TLS connection can involve negotiating and retrying, in order to select a secure protocol that is supported by both client and server. The BlackBerry Dynamics runtime handles client-side negotiation and retrying, if secure communication is in use.

By default, the runtime won't offer the TLSv1.1 or TLSv1.2 protocols for SSL/TLS connections with an application server.

The runtime can be configured to offer these protocols, as follows.

  1. Add a new row to the application's Info.plist file*:
    • Key: GDControlTLSVersions
    • Type: String (the default)
  2. Set the value to:
    • GDEnableTLS1.1 to enable the TLSv1.1 protocol.
    • GDEnableTLS1.2 to enable both TLSv1.1 and TLSv1.2 protocols.
    As an alternative, the value can instead be an array containing one or both of the above strings as separate items.

(*In case there are multiple Info.plist files, check that the correct one has been edited by opening the Info tab of the application target being built. The setting just made should appear there.)

The setting only affects connections to application servers, not the connection with the BlackBerry Dynamics infrastructure itself. The protocols aren't offered by default because there are many installed web servers with which a connection cannot be established after one of these protocols has been offered.

In addition to the above, the following protocol versions can be blocked by enterprise management console configuration.

  • SSLv3
  • TLSv1.0
  • TLSv1.1
  • TLSv1.2

The configuration of blocked protocol versions can be done in the enterprise management console user interface. The configuration applies at the deployment level and isn't specific to user, policy group, or application server. The block only affects communication with application servers that is routed via the BlackBerry Dynamics proxy infrastructure.

Enterprise server connection notes

BlackBerry Dynamics secure communication can be used to connect to servers that are behind the enterprise firewall. This applies to socket connections and HTTP requests. Note the following when using this capability.

The addresses of any application servers to which connection is being made must be configured in the enterprise management console. The address could be registered as the application's server, or as an additional server, for example.

Note. The application server configuration set in the management console can be obtained in the application code by using the getApplicationConfig (GDiOS) function.

The connection to the application server will be made through the BlackBerry Dynamics proxy infrastructure. The status of the application's connection to the proxy infrastructure can be checked and monitored by using the GDReachability interface.

See also:
System administration tasks for application developers
GDReachability class reference.

Member Function Documentation

- (instancetype) init: (const char *)  url
onPort: (int)  port
andUseSSL: (BOOL)  ssl 

Call this function when constructing a new GDSocket object. This function doesn't initiate data communication, compare connect.

Parameters:
urlNull-terminated string containing the address of the server. Can be either an Internet Protocol address (IP address, for example "192.168.1.10"), or a fully qualified domain name (for example "www.example.com").
portNumber of the server port to which the socket will connect.
sslNO to use no security, YES to use SSL/TLS security.
See also:
SSL/TLS Security, above
- (BOOL) disableHostVerification

This function switches off host name verification, when making an SSL/TLS connection. Host name verification is an SSL/TLS security option.

Host Name Verification
When negotiating an SSL/TLS connection, the server sends a certificate indicating its identity. The certificate includes a number of host names. By default, one of the host names in the certificate must match with the host name specified by the client, or the connection fails.
If host name verification is switched off, the connection succeeds regardless of whether there is a matching host name in the certificate.
If switched on, the BlackBerry Dynamics runtime checks server identity in a way that conforms with the relevant RFC. See under section 3.1 Server Identity, in RFC2818.

This function must be called before connect.

Switching off host name verification doesn't switch off authenticity verification, see disablePeerVerification.

Returns:
YES if the security option was successfully disabled.
NO if the security option could not be disabled.
See also:
SSL/TLS Security, above
- (BOOL) disablePeerVerification

This function switches off certificate authenticity verification, when making an SSL/TLS connection. Authenticity verification is an SSL/TLS security option.

Certificate Authenticity Verification
When negotiating an SSL/TLS connection, the server sends a certificate indicating its identity. By default, the certificate must be verified as trustworthy, or the connection fails. In this context, trustworthiness derives from a chain of digital signatures, rooted in a certification authority.
If authenticity verification is switched off, the connection succeeds regardless of the certificate's trustworthiness.
If authenticity verification is switched on, the BlackBerry Dynamics runtime checks certificate trustworthiness using operating system services. See the Certificate, Key, and Trust Services API Reference on the apple.com developer website.

This function must be called before connect.

Switching off authenticity verification implicitly also switches off host name verification, see disableHostVerification.

Returns:
YES if the security option was successfully disabled.
NO if the security option could not be disabled.
See also:
SSL/TLS Security, above
- (void) connect

Call this function to open the socket connection.

The connection attempt is asynchronous. If the attempt succeeds, the delegate onOpen callback is invoked.

- (void) write

Call this function to send data through the socket connection. The data must previously have been added to the socket's outbound buffer, represented by the writeStream property.

- (void) disconnect

Call this function to terminate the socket connection.

Disconnection is asynchronous. When disconnection completes, the delegate onClose callback is invoked.


Property Documentation

- (id<GDSocketDelegate>) delegate [read, write, assign]

The BlackBerry Dynamics socket interface is asynchronous. When socket state changes, or data is received, a callback in the application code is invoked by the BlackBerry Dynamics runtime.

Set this property to an instance of a class that contains the code for the required callback functions, i.e. a class that implements the GDSocketDelegate protocol.

- (GDDirectByteBuffer *) writeStream [read, write, assign]

This property represents the outbound buffer of the socket. Data to be sent through the socket is first written to this buffer, using the GDDirectByteBuffer interface, then sent by calling write.

The outbound buffer can be accessed whenever this property isn't null.

- (GDDirectByteBuffer *) readStream [read, write, assign]

This property represents the inbound buffer of the socket. When data is received through the socket, the following takes place:

  • The data is stored in the inbound buffer,
  • The delegate onRead callback is invoked.

Received data should then be consumed from the buffer, using the GDDirectByteBuffer interface.

The inbound buffer can be accessed whenever this property isn't null.


The documentation for this class was generated from the following file: