BlackBerry Spark Communications Services for iOS  1.9.0
BBMEnterpriseService Class Reference
Inheritance diagram for BBMEnterpriseService:

Public Types

enum  BBMSDKLogMode : NSUInteger { kBBMLogModeFile, kBBMLogModeConsole, kBBMLogModeFileAndConsole }
 
enum  BBMSDKLogLevel : NSUInteger { kLogLevelDefault, kLogLevelVerbose }
 

Instance Methods

(BBMMediaManager *) - mediaManager
 
(void) - setAccessGroupIdentifier:
 
(void) - start:environment:completionBlock:
 
(BOOL) - stop
 
(void) - sendAuthToken:userIdentifier:setupStateBlock:
 
(BBMDSGeneratedModel *) - model
 
(void) - sendMessageToService:
 
(BOOL) - resetService
 
(void) - addListener:forMessageNames:
 
(void) - removeListener:forMessageNames:
 
(void) - addListener:forMessageTypes:
 
(void) - removeListener:forMessageTypes:
 
(void) - pushReceived:
 
(void) - setPushToken:
 
(void) - setPushToken:type:
 
(void) - addConnectivityListener:
 
(void) - removeConnectivityListener:
 
(NSLock *) - readWriteLock
 
(void) - setLogLevel:
 
(void) - setLoggingMode:
 
(NSString *) - logDirectory
 

Class Methods

(instancetype) + service
 
(instancetype) + sharedService
 

Properties

BBMCoreServiceState serviceState
 
BOOL connectionIsAvailable
 

Detailed Description

This class provides a way to start the BBM Enterprise service. Once the service has started an authorization token and a user name have to be sent so that the app can start performing any activities such as sending and receiving messages. This can be done by accessing BBMServiceLayer which provides access to the data model. This class also provides access to an instance of BBMMediaManager which can be used to start and receive voice and video calls.

Since
R3

Member Enumeration Documentation

◆ BBMSDKLogLevel

- (enum BBMSDKLogLevel) :
Enumerator
kLogLevelDefault 

Default log level.

kLogLevelVerbose 

Verbose log level.

◆ BBMSDKLogMode

- (enum BBMSDKLogMode) :
Enumerator
kBBMLogModeFile 

Print SDK logs to file only.

kBBMLogModeConsole 

Print SDK logs to console only.

kBBMLogModeFileAndConsole 

Print SDK logs to console and file.

Method Documentation

◆ addConnectivityListener:()

- (void) addConnectivityListener: (id< BBMConnectivityListener >)  listener

The listener added in this method will get notified any time there is a change in the service connection state. This callback can be used to tell the user if there is connectivity to the service or not.

Parameters
listenerThe object that will get notified if there is a change.
Since
R4

◆ addListener:forMessageNames:()

- (void) addListener: (id< BBMIncomingMessageListener >)  listener
forMessageNames: (NSArray *)  messageNames 

Adds a listener for the message names specified. Every time a message that matches a name arrives it will be forwarded to the listener. The name of the message is determined by the key of the root object. All listeners are removed automatically when the service is stopped. This method will throw an exception if a listener is added before the service is started.

// Example of message with name "listElements":
{
"listElements": {
"type": "user"
}
}
Parameters
listenerThe object that will receive the message.
messageNamesAn array of message names that the consumer is interested in.
Exceptions
BBMEntperpriseServiceMisuseExceptionIf the listener is added before the service is started.
Since
R4

◆ addListener:forMessageTypes:()

- (void) addListener: (id< BBMIncomingMessageListener >)  listener
forMessageTypes: (NSArray *)  messageTypes 

Adds a consumer for the message types specified. Every time a message that matches the types arrives it will be forwarded to the consumer. The type of the message is determined by the type field in the message. All listeners are removed automatically when the service is stopped. This method will throw and execption if a listener is added before the service is started.

// Example of message with type "user":
{
"listElements": {
"type": "user"
}
}
Parameters
listenerThe object that will receive the message
messageTypesAn array of type names that the consumer is interested in.
Exceptions
BBMEntperpriseServiceMisuseExceptionIf the listenter is added before the service is started.
Since
R4

◆ logDirectory()

- (NSString *) logDirectory

Returns the filesystem path to the internal logs

Returns
NSString Local directory containing the internal SDK log files
Since
R4

◆ mediaManager()

- (BBMMediaManager *) mediaManager

Returns a shared instance of the BBM media manager. Use this instance for all interactions with the voice and video services.

Returns
BBMMediaManager The shared BBMMediaManager object.
Since
R3

◆ model()

- (BBMDSGeneratedModel *) model

Returns a reference to the root node of the BBM data model.

Returns
BBMDSGeneratedModel A reference to the root node of the BBM data model.
Since
R4

◆ pushReceived:()

- (void) pushReceived: (NSDictionary *)  json

This method must be called whenever you receive a push payload that originated from the BBM server. This will wake the service layer and fetch any pending data and/or attempt to connect any waiting calls. Do not forward pushes here that do not originate from the BBM server.

Parameters
jsonThe raw json dictionary of the push payload returned by PKPushRegistry payload.dictionaryPayload
Since
R4

◆ readWriteLock()

- (NSLock *) readWriteLock

You must acquire this lock before reading any observable properties off the main thread. All BBM model object properties are observable as are several properties exposed by BBMEnterpriseService and BBMMediaManager and their associated classes.

Do not hold this lock for long periods of time as it will block updates to the data model.

An ObservableTracker Misuse exception will be thrown if an observable property is read off of the main thread without first calling [[[BBMEnterpriseService shared] readWriteLock] lock]

Observable properties are NOT tracked when they are read off of the main thread.

self.identifierMonitor = [ObservableMonitor monitorActivatedWithName:@"identifierMonitor" block:^{
//Do some things on the main thread
dispatch_async(dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
//Acquire the lock
//It is now safe to read observable properties. We are guaranteed that the data model
//will not change while we hold this lock. Note that reading this property will not trigger
//the enclosing observable monitor as we are now off of the main thread.
id theVar = myBBMDSObject.property
//Release the lock as soon as we are done reading
[[[BBMEnterpriseService shared] readWriteLock] unlock];
//Do some things with theVar
});
}];
Returns
NSLock Locked when a write operation is taking place to the data model.
Since
R4

◆ removeConnectivityListener:()

- (void) removeConnectivityListener: (id< BBMConnectivityListener >)  listener

If a listener is no longer interested in changes in the service connection state it can be removed as a listener by calling this method.

Parameters
listenerThe object that will get removed as a listener.
Since
R4

◆ removeListener:forMessageNames:()

- (void) removeListener: (id< BBMIncomingMessageListener >)  listener
forMessageNames: (NSArray *)  messageNames 

Removes listener so that messages that match specified message names are no longer forwarded to the listener

Parameters
listenerThe object that will be removed as a listener
messageNamesAn array of message names that the listener is no longer interested in.
Since
R4

◆ removeListener:forMessageTypes:()

- (void) removeListener: (id< BBMIncomingMessageListener >)  listener
forMessageTypes: (NSArray *)  messageTypes 

Removes listener so that messages that match specified message types are no longer forwarded to the listener

Parameters
listenerThe object that will be removed as a listener
messageTypesAn array of type names that the listener is no longer interested in.
Since
R4

◆ resetService()

- (BOOL) resetService

Triggers BBM Enterprise service to wipe all its data. This will cause all data in BBM Enterprise to be cleared taking the client back to its initial state. BBM Enterprise must have been started for the reset to succeed. When this call is done, BBM Enterprise will restart underlying objects and return to a started state.

Note
As of R5, this will now return YES if the message was sent to reset the service. NO, if the service was in a state where the messages could not be sent (ie: not started)
Returns
BOOL YES if the reset succeeded
Since
R4

◆ sendAuthToken:userIdentifier:setupStateBlock:()

- (void) sendAuthToken: (NSString *)  authToken
userIdentifier: (NSString *)  userIdentifier
setupStateBlock: (SetupStateBlock setupStateBlock 

Sends the authorization token for a user. This should be called after the service has started.

Parameters
authTokenThe authorization token.
userIdentifierA unique user identifier. Typically the oAuth identifier. This must be globally unique and must not change for the lifetime of the user.
setupStateBlockThe block that gets called when there is a change in the setup process.
Since
R6

◆ sendMessageToService:()

- (void) sendMessageToService: (BBMJSONMessage *)  message

Sends a message to the core service.

Parameters
messageThe JSON message to send to the core service.
Since
R4

◆ service()

+ (instancetype) service

Returns the global shared instance of the BBMEnterpriseService.

Returns
The shared BBMEnterpriseService object.
Since
R3

◆ setAccessGroupIdentifier:()

- (void) setAccessGroupIdentifier: (NSString *)  accessGroupIdentifier

Sets the keychain access group identifier for your application. This allows the sharing of encyrption keys between your application and any notification extensions if you're using the BBMKeyGenerator class for generating and persisting keys. This must be called before you start the service or the accessGroupIdentifer will be automatically set to nil and keys will not be availble via BBMKeyGenerator to any application extensions.

Parameters
accessGroupIdentifierThe keychain access group identifier specified in your app entitlements
Since
R11

◆ setLoggingMode:()

- (void) setLoggingMode: (BBMSDKLogMode logMode

Set the desired logging mode for the SDK. The default is to kBBMLogModeFile.

Since
R4

◆ setLogLevel:()

- (void) setLogLevel: (BBMSDKLogLevel logLevel

Sets the log level. This will override the default settings, HOWEVER, this will only take effect on a fresh install of the application and only if it is called before the service is started. Changing this value after the application is already installed has no effect. This can only be set to kLogLevelDefault when using the Production environment. A BBMESecurityException will be thrown if kLogLevelVerbose is used when the service is configured to use the production environment.

Parameters
logLevelThe desired log verbosity
Since
R4

◆ setPushToken:()

- (void) setPushToken: (NSData *)  DEPRECATED_ATTRIBUTE

This method is deprecated. Use setPushToken:type: instead. This is now the equivalent of setPushToken:token type:BBMVoipToken

Parameters
tokenThe PushKit token returned by PKPushKit PKPushCredentials.token
Since
R4
Deprecated:
R11

◆ setPushToken:type:()

- (void) setPushToken: (NSData *)  token
type: (BBMTokenType type 

Upon receiving a token or a token update from PushKit (for the VOIP token) or via the app delegate methods (for the APNS token), it must be sent to the service via this method. This will automatically update the push tokens in the service. If you are using your own APNS server, this method must be ignored.

Parameters
tokenThe PushKit or APNS token
typeThe token type
Since
R11

◆ sharedService()

+ (instancetype) sharedService

Equivalent to service. Use this implementation for Swift apps (via .shared())

Returns
The shared BBMEnterpriseService object
Since
R4

◆ start:environment:completionBlock:()

- (void) start: (NSString *)  userDomain
environment: (BBMConfigEnvironment env
completionBlock: (void(^)(BOOL success))  completion 

Start the BBM Enterprise service. This must be called before any BBME calls can be placed or received. A user domain is required. Apps running under the same user domain can interact with each other. The completion block gets called every time there is a change in the state of the service.

Exceptions
BBMEServiceMisuseIf the service is currently started. You must call stop before restarting.
Parameters
userDomainThe user domain of the app.
envThe environment the app will be running in (ignored after first execution of each app version).
completionThe block that gets called every time there is a change in the state of the service.
Since
R3

◆ stop()

- (BOOL) stop

Attempts to stop the BBM Enterprise service. If successful, any BBME calls will be ignored until the service starts again. Stopping the service may take a few seconds. Once the service stops, serviceState will be updated.

Returns
YES means the service will attempt to stop. NO means the service was unable to stop.
Since
R4

Property Documentation

◆ connectionIsAvailable

- (BOOL) connectionIsAvailable
readnonatomicassign

YES if the BBME service is currently connected

Note
This is not KVO observable. Use addConnectivityListener to observe changes in the connection state.
Since
R4

◆ serviceState

- (BBMCoreServiceState) serviceState
readatomicassign

Returns the current state of the BBM Enterprise service. This value can be observed using an instance of ObservableMonitor.

Since
R4