-
- BlackBerry Dynamics
- Runtime library for iOS applications
- 11.1.0.62
TCP socket, supporting SSL/TLS and communication across the firewall. More...
#import <GDNETiOS.h>
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.
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.
| State | Functions / Actions | Expected callbacks |
|---|---|---|
| Prepared | Application can call connect: state becomes ConnectingApplication can call disableHostVerification: no state changeApplication can call disablePeerVerification: no state change | None |
| Connecting | Open socket connection to server |
|
| Open | Application can call disconnect: state becomes DisconnectingApplication can call write: No state change |
|
| Disconnecting | Close socket connection |
|
| 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 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.
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:
andUseSSL: YES in the call to the init function.disableHostVerification and disablePeerVerification are used to reduce the level of security checking. Setting disablePeerVerification implicitly sets disableHostVerification.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.
GDControlTLSVersionsString (the default)GDEnableTLS1.1 to enable the TLSv1.1 protocol.GDEnableTLS1.2 to enable both TLSv1.1 and TLSv1.2 protocols.(*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.
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.
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.
Instance Methods | |
| (instancetype) | - init:onPort:andUseSSL: |
| Constructor that prepares a new socket. More... | |
| (BOOL) | - disableHostVerification |
| Security option: Switch off SSL/TLS host name verification. More... | |
| (BOOL) | - disablePeerVerification |
| Security option: Disable SSL/TLS authenticity verification. More... | |
| (void) | - connect |
| Connect the socket. More... | |
| (void) | - write |
| Send data from the writeStream buffer. More... | |
| (void) | - disconnect |
| Terminate the socket connection. More... | |
Properties | |
| id< GDSocketDelegate > | delegate |
| Handler for state changes and received data. More... | |
| GDDirectByteBuffer * | writeStream |
| Outbound buffer. More... | |
| GDDirectByteBuffer * | readStream |
| Inbound buffer. More... | |
| - (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.
| url | Null-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"). |
| port | Number of the server port to which the socket will connect. |
| ssl | NO to use no security, YES to use SSL/TLS security. |
| - (BOOL) disableHostVerification |
This function switches off host name verification, when making an SSL/TLS connection. Host name verification is an SSL/TLS security option.
This function must be called before connect.
Switching off host name verification doesn't switch off authenticity verification, see disablePeerVerification.
YES if the security option was successfully disabled. NO if the security option could not be disabled.| - (BOOL) disablePeerVerification |
This function switches off certificate authenticity verification, when making an SSL/TLS connection. Authenticity verification is an SSL/TLS security option.
This function must be called before connect.
Switching off authenticity verification implicitly also switches off host name verification, see disableHostVerification.
YES if the security option was successfully disabled. NO if the security option could not be disabled.| - (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.
|
readwritenonatomicweak |
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.
|
readwritenonatomicstrong |
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.
|
readwritenonatomicstrong |
This property represents the inbound buffer of the socket. When data is received through the socket, the following takes place:
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.