public interface SinchClient

The SinchClient is the Sinch SDK entry point.

It provides access to the feature classes in the Sinch SDK: MessageClient, CallClient and AudioController. It is also used to configure the user's and device's capabilities.

The user IDs that are used to identify users application specific. If the app already has a scheme for user IDs (email addresses, phone numbers, customer numbers, etc.), the same ID could be used when configuring the SinchClient.

Example

 
 // Instantiate a SinchClient
 android.content.Context context = this.getApplicationContext();
 SinchClient sinchClient = Sinch.getSinchClientBuilder().context(context)
                                                   .applicationKey("<application-key>")
                                                   .applicationSecret("<application-secret>")
                                                   .environmentHost("sandbox.sinch.com")
                                                   .userId("<user id>")
                                                   .build();

 // Specify the client capabilities. At least one of the messaging or calling capabilities should be enabled.
 sinchClient.setSupportMessaging(true);
 sinchClient.setSupportCalling(true);
 sinchClient.setSupportActiveConnectionInBackground(true);
 sinchClient.setSupportPushNotifications(true);


 // Add the client listener that handles client state changes.
 sinchClient.addSinchClientListener(...);

 // Start the client
 sinchClient.start();

 ...

 // Use the MessageClient to send and receive messages
 // Use the CallClient to place and receive calls

 // Stop listening for incoming events (calls or messages).
 sinchClient.stopListeningOnActiveConnection();

 // Stop the client when the calling or messaging functionality is no longer needed.
 sinchClient.stop();

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addSinchClientListener(SinchClientListener sinchClientListener)` The `SinchClientListener` object handles events from the `SinchClient` such as incoming calls.
`void`	`checkManifest()` This method should be called before `start()` and be used during development time to verify that the manifest contains the permissions required.
`AudioController`	`getAudioController()` Returns an `AudioController` object for controlling different audio settings.
`CallClient`	`getCallClient()` Returns the `CallClient` object for placing and receiving calls.
`java.lang.String`	`getLocalUserId()` Returns the id of the user associated with this `SinchClient`.
`MessageClient`	`getMessageClient()` Deprecated. Instant Messaging no longer supported.
`VideoController`	`getVideoController()` Returns a `VideoController` object for managing and retrieving views for Video calls.
`boolean`	`isStarted()` Returns `true` if the `SinchClient` is started.
`void`	`registerPushNotificationData(byte[] pushNotificationData)` Register device specific data that can be used to identify this device and tie it to a GCM registration identifier.
`NotificationResult`	`relayRemotePushNotificationPayload(android.content.Intent intent)` Method used to forward the intent received from GCM.
`NotificationResult`	`relayRemotePushNotificationPayload(java.util.Map<java.lang.String,java.lang.String> payload)` Method used to forward the intent received from FCM.
`NotificationResult`	`relayRemotePushNotificationPayload(java.lang.String payload)` Method used to forward the Sinch specific payload extracted from an incoming Google Cloud Messaging message.
`void`	`removeSinchClientListener(SinchClientListener sinchClientListener)` Remove listener for client events.
`void`	`setMediaHandover(boolean enable)` Enables and disables media handover functionality.
`void`	`setPushNotificationDisplayName(java.lang.String displayName)` Specify a display name to be used when the Sinch client sends a push notification on behalf of the local user (e.g.
`void`	`setSupportActiveConnectionInBackground(boolean supported)` If you intend to listen for incoming calls in a background service of some sort you must enable this.
`void`	`setSupportCalling(boolean supported)` If you intend to make or receive calls you must enable this.
`void`	`setSupportManagedPush(boolean enabled)` Enables the use of managed push, where Sinch is responsible for sending your app a push notification when necessary.
`void`	`setSupportMessaging(boolean supported)` If you intend to send and/or receive messages you must enable this.
`void`	`setSupportPushNotifications(boolean supported)` If you implement support for push notifications, such as GCM, you must enable this.
`void`	`start()` Starts the Sinch client.
`void`	`startListeningOnActiveConnection()` Start listening for incoming calls.
`void`	`stop()` Deprecated. As of release 3.0.1, replaced by `terminate()`
`void`	`stopListeningOnActiveConnection()` Stop listening for incoming calls.
`void`	`terminate()` Terminates the Sinch client.
`void`	`terminateGracefully()` Terminates the Sinch client, while still leaving it some time to finish up currently pending tasks, for example finishing pending HTTP requests.
`void`	`unregisterManagedPush()` Deprecated. Use `ManagedPush.unregisterPushToken()`.
`void`	`unregisterPushNotificationData()` Unregister previously registered device specific data that is used to identify this device and tie it to a GCM registration identifier.

- Method Detail
  - setSupportMessaging
```
void setSupportMessaging(boolean supported)
```
    If you intend to send and/or receive messages you must enable this.
    
    Parameters:
    
    supported - whether or not the application supports instant messaging.
  - setSupportCalling
```
void setSupportCalling(boolean supported)
```
    If you intend to make or receive calls you must enable this.
    
    Parameters:
    
    supported - whether or not the application supports calling.
  - setSupportActiveConnectionInBackground
```
void setSupportActiveConnectionInBackground(boolean supported)
```
    If you intend to listen for incoming calls in a background service of some sort you must enable this. Note that the actual background service must be implemented by the application. This is merely an instruction to the SinchClient.
    
    Parameters:
    
    supported - whether or not the application uses an active connection in the background.
  - setSupportPushNotifications
```
void setSupportPushNotifications(boolean supported)
```
    If you implement support for push notifications, such as GCM, you must enable this. This instructs the SinchClient that this application is capable of receiving push notifications.
    
    Parameters:
    
    supported - whether or not the application supports push notifications.
  - setSupportManagedPush
```
void setSupportManagedPush(boolean enabled)
                    throws MissingGCMException
```
    Enables the use of managed push, where Sinch is responsible for sending your app a push notification when necessary.
    
    Parameters:
    
    enabled - whether or not managed push is enabled
    
    Throws:
    
    MissingGCMException - If the device does not have Google Play Services installed.
  - checkManifest
```
void checkManifest()
```
    This method should be called before start() and be used during development time to verify that the manifest contains the permissions required. Once the application is ready to be published any calls to this manifest can be removed.
    
    Throws:
    
    MissingPermissionException - if any of the required permissions are missing.
  - getCallClient
```
CallClient getCallClient()
```
    Returns the CallClient object for placing and receiving calls.
    
    Returns:
    
    the CallClient object.
    
    Throws:
    
    java.lang.IllegalStateException - if setSupportCalling(boolean) is not enabled.
  - getMessageClient
```
@Deprecated
MessageClient getMessageClient()
```
    Deprecated. Instant Messaging no longer supported.
    
    Returns the MessageClient object for sending messages and adding listeners for message events.
    
    Returns:
    
    the MessageClient object.
    
    Throws:
    
    java.lang.IllegalStateException - if setSupportMessaging(boolean) is not enabled.
  - addSinchClientListener
```
void addSinchClientListener(SinchClientListener sinchClientListener)
```
    The SinchClientListener object handles events from the SinchClient such as incoming calls.
    
    Parameters:
    
    sinchClientListener - a SinchClientListener
  - removeSinchClientListener
```
void removeSinchClientListener(SinchClientListener sinchClientListener)
```
    Remove listener for client events.
    
    Parameters:
    
    sinchClientListener - a SinchClientListener
  - start
```
void start()
```
    Starts the Sinch client. This must be done prior to making any calls or calling startListening.
    
    Throws:
    
    java.lang.IllegalStateException - if SinchClient is already started
    
    MissingPermissionException - if SinchClient detects that the app lacks required Android permissions
  - isStarted
```
boolean isStarted()
```
    Returns true if the SinchClient is started.
    
    Returns:
    
    true if the SinchClient is started.
  - stop
```
@Deprecated
void stop()
```
    Deprecated. As of release 3.0.1, replaced by terminate()
    
    Stops the Sinch client.
    Since version 1.2.0 SinchClient.stop() does no longer throw an IllegalStateException if SinchClient was not started. This change was made so that any application can call SinchClient.stop() on shut down so it is never forgotten.
  - terminate
```
void terminate()
```
    Terminates the Sinch client.
  - terminateGracefully
```
void terminateGracefully()
```
    Terminates the Sinch client, while still leaving it some time to finish up currently pending tasks, for example finishing pending HTTP requests.
  - startListeningOnActiveConnection
```
void startListeningOnActiveConnection()
```
    Start listening for incoming calls.
  - stopListeningOnActiveConnection
```
void stopListeningOnActiveConnection()
```
    Stop listening for incoming calls.
  - registerPushNotificationData
```
void registerPushNotificationData(byte[] pushNotificationData)
```
    Register device specific data that can be used to identify this device and tie it to a GCM registration identifier.
    
    Parameters:
    
    pushNotificationData - Device specific data that can be used to tie a device to a specific GCM registration identifier.
    The pushNotificationData is what will be passed back in CallListener.onShouldSendPushNotification(com.sinch.android.rtc.calling.Call, java.util.List<com.sinch.android.rtc.PushPair>) in the caller's application, unless the application on the destination device (the device on which this method is called) is not running in the background.
    
    Throws:
    
    java.lang.IllegalStateException - If the user does not have push capability enabled
  - unregisterPushNotificationData
```
void unregisterPushNotificationData()
```
    Unregister previously registered device specific data that is used to identify this device and tie it to a GCM registration identifier.
  - unregisterManagedPush
```
@Deprecated
void unregisterManagedPush()
```
    Deprecated. Use ManagedPush.unregisterPushToken().
    
    Unregister this device from receiving push messages sent by the Sinch backend. This should be called if a user logs out or takes a similar action in your application. Prevents any further push messages to this device until a new SinchClient is started with managed push enabled.
  - relayRemotePushNotificationPayload
```
NotificationResult relayRemotePushNotificationPayload(java.lang.String payload)
```
    Method used to forward the Sinch specific payload extracted from an incoming Google Cloud Messaging message. This will implicitly start the SinchClient if it wasn't already started.
    
    Parameters:
    
    payload - Sinch specific payload which was transferred with the message
    
    Returns:
    
    A result indicating initial inspection of the payload.
  - relayRemotePushNotificationPayload
```
NotificationResult relayRemotePushNotificationPayload(android.content.Intent intent)
```
    Method used to forward the intent received from GCM. This will automatically extract the sinch specific payload, if available. This will implicitly start the SinchClient if it wasn't already started.
    
    Parameters:
    
    intent - Intent received from a GCM receiver
    
    Returns:
    
    A result indicating initial inspection of the payload.
    
    See Also:
    
    SinchHelpers.isSinchPushIntent(Intent), relayRemotePushNotificationPayload(String)
  - relayRemotePushNotificationPayload
```
NotificationResult relayRemotePushNotificationPayload(java.util.Map<java.lang.String,java.lang.String> payload)
```
    Method used to forward the intent received from FCM. This will automatically extract the sinch specific payload, if available. This will implicitly start the SinchClient if it wasn't already started.
    
    Parameters:
    
    payload - Payload received from a FCM RemoteMessage data
    
    Returns:
    
    A result indicating initial inspection of the payload.
    
    See Also:
    
    SinchHelpers.isSinchPushPayload(java.util.Map), relayRemotePushNotificationPayload(String)
  - setPushNotificationDisplayName
```
void setPushNotificationDisplayName(java.lang.String displayName)
```
    Specify a display name to be used when the Sinch client sends a push notification on behalf of the local user (e.g. for an outgoing call). This will only be used when using setSupportManagedPush(boolean)). Display name is included in a push notification on a best-effort basis. For example, if the target device has very limited push payload size constraints (e.g iOS 7 can only handle 255 byte push notification payload), then the display name may not be included.
    
    Parameters:
    
    displayName - display name may at most be 255 bytes (UTF-8 encoded) long.
  - setMediaHandover
```
void setMediaHandover(boolean enable)
```
    Enables and disables media handover functionality. When media handover is enabled, call started on WiFi network will continue after WiFi is lost if cellular connectivity is available. Set to false to prevent it to happen, say, if WiFi-only calls are desired. NB: when disabled, it still allows call to be started on cellular, so it is the client's responsibility to control the start of the call.
    
    Parameters:
    
    enable - equal to false disables media handover from WiFi to cellular when WiFi is lost.
  - getLocalUserId
```
java.lang.String getLocalUserId()
```
    Returns the id of the user associated with this SinchClient.
    
    Returns:
    
    the local user id.
  - getAudioController
```
AudioController getAudioController()
```
    Returns an AudioController object for controlling different audio settings. You may only call this method while the SinchClient is started.
    
    Returns:
    
    an AudioController object for controlling audio settings.
    
    Throws:
    
    java.lang.IllegalStateException - if SinchClient isn't started.
  - getVideoController
```
VideoController getVideoController()
```
    Returns a VideoController object for managing and retrieving views for Video calls.
    
    Returns:
    
    an VideoController object for controlling video settings.

Interface SinchClient

Example

Method Summary

Method Detail

setSupportMessaging

setSupportCalling

setSupportActiveConnectionInBackground

setSupportPushNotifications

setSupportManagedPush

checkManifest

getCallClient

getMessageClient

addSinchClientListener

removeSinchClientListener

start

isStarted

stop

terminate

terminateGracefully

startListeningOnActiveConnection

stopListeningOnActiveConnection

registerPushNotificationData

unregisterPushNotificationData

unregisterManagedPush

relayRemotePushNotificationPayload

relayRemotePushNotificationPayload

relayRemotePushNotificationPayload

setPushNotificationDisplayName

setMediaHandover

getLocalUserId

getAudioController

getVideoController