Change History
Update SDK, add hlBth.jar, hlvoipCall.aar and hlvoipCfg.aar
Update the Key Events chapter
1. Introduction
Htek UCV series phone is developed on the platform. This guide introduce the Htek's Android SDK to help the developers use the APIs.
1.1 Supported Models
Model | Firmware | |
UCV10 series | 5.42.1.7.1.32 or higher | |
UCV20 series | 5.42.1.7.1.32 or higher | |
UCV50 series | 5.42.1.7.1.32 or higher | |
UCV52 series | 5.42.1.7.1.32 or higher | |
UCV53 series | 5.42.1.7.1.32 or higher |
2. Application Building
Here is the necessary steps to build the application with Htek Android SDK.
2.1 Put JAR under directory app/libs
2.2 Add dependence in build.gradle
dependencies {
......
implementation(files("libs/hlvoipCfg-release.aar"))
implementation(files("libs/hlvoipCall-release.aar"))
implementation(files("libs/hlBth.jar"))
compileOnly(files('libs/hlsys.jar'))
......
}
2.3 Add API key in AndroidManifest.xml
To get an API key, please follow Request an API Key
<manifest xxxx>
<application
...
<meta-data
android:name="api_key" android:value="/{api_key}" />
</application>
</manifest xxxx>/>
3 Component Introduction
The VoIP API refers to a set of interfaces for developing applications based on Htek Android phones.
3.1 hlsys.jar
Provide support for Scene system, audio control, key event, LED control and USB headset control.
Refer to:
3.2 hlBth.jar
Provide support for Htek BT handset.
3.3 hlVoipCfg
Used to get and set the configurations of Htek VoIP
import com.htek.cfg.utils.CfgUtils; //Get and set configurations //[xxxx] is of Int, String, Float, Double CfgUtils.getCfg[xxxx]Value() CfgUtils.setCfg[xxxx]Value() //Get and set account info： List<VoipAccount> CfgUtils.loadAccounts() VoipAccount getAccount() updateAccount() VoipAccount getDefaultAccount() setDefaultAccount() //Get and set account configurations； List<VoipProfile> CfgUtils.loadProfiles() VoipProfile CfgUtils.getProfile() updateProfile()
Refer to: Htek SDK Demo
3.4 hlVoipCall
Used to makes call and answers call through Htek VoIP.
Htek VoIP is the built-in call component on the phone, if your APP has its own call function, you don’t need use this component.
import com.htek.call.utils.CallMaker;
CallMaker.call()
interface VoipInCallPresenter.PresenterListener{
default void onServiceBind(VoipInCallService service){}
default void onServiceUnbind(){}
default void onCallAdded(Call call){}
default void onCallRemoved(Call call){}
default void onCanAddCallChanged(boolean canAddCall){}
default void onForwardInCall(){}
default void onBringToForeground(boolean showDialpad){}
default void onCallAudioStateChanged(CallAudioState audioState){}
default void onSilenceRinger(){}
default void onConnectionEvent(Call call, String event, Bundle extras){}
}
Refer to: Htek SDK Demo
4. Scene System
4.1 Introduction of Scene System
When using an Htek Android phone, there are many states, which the phone may be in one of them when you operate the phone.
Depending on the state, the phone responses differently to the same command/action.
For example, when you using the dialpad, and at the same time, you pickup the handset, the phone will call the number if you have already input some numbers, or it will switch to handset mode if you haven't input anything.
We call the current state of the phone a scene, and we use Scene System to manage the scene switching.
Below table lists some scenes as an example:
Action → | Pickup handset | Press handsfree button | Press headset button |
|---|---|---|---|
Idle | Enter dialpad | Enter dialpad | Switch headset priority mode |
Using an app (not in talking) | Enter dialpad | Enter dialpad | Switch headset priority mode |
Play Music | Using handset play | Using handsfree play | Using headset play |
Using 3rd-party app talking | Switch to handset mode | Switch to handsfree mode | Switch to headset mode |
Using dialpad | If already dial nubmers, call out using handset; else, | If already dial nubmers, call out using handsfree; else, | If already dial nubmers, call out using headset; else, |
Using built-in VOIP app talking | Switch to handset mode | If already in handsfree mode, end up the call; else, | If already in headset mode, end up the call; else, |
4.2 Scene Client and Scene Manager
The scene system consists of scene client and scene manager.
4.2.1 Scene Manager
The SceneManager is a system service, and you can get an instance through this way:
SceneManager sceneManager = context.getSystemService(SceneManager.class);
Here is a list of all interfaces supported by the Scene Manager.
Expand the below block.
4.2.2 Scene Client
Implement a Scene Client and register it to Scene Manager so you can use it to handle events. You may have multi Scene Clients, but only the one which has the highest priority will be active to work. (refer to Scene Priority)
The interface of Scene Client is as below:
interface ISceneClient {
void enter();
void exit();
boolean onDialpadPress(char c, boolean replace);
boolean onUnhandleKeyEvent(int KeyEvent event);
boolean onAudioDeviceChanged();
boolean onEhsEvent(int ehsEvent);
String getName();
}
Interface | Parameters | Return Value | Comments |
|---|---|---|---|
enter | void | ||
exit | void | If there is another Scene Client has higher priority exists, or unregister this Scene Client, exit() will be called. | |
getName | String | Need to implement to return the name of Scene Client. | |
onAudioDeviceChanged | true: if it is no need to use system default audio device switching mechanism; | Generally, return false is recommended. | |
onDialpadPress | c: the currently input character (0~9, *, #). | true: Dialpad press event will not be deliver to the currently active app | This callback doesn't run in UI threading, please avoid executing blocking tasks here. |
onEhsEvent | ehsEvent: EHS Event | true: if the EHS event is handled | If you don't need EHS, you don't need to implement it, and you can just return false. |
onUnhandleKeyEvent | event： unhandled key event | true: if the key event is handled |
4.3 Key Event Dispatch with Scene System
The key event dispatch of Htek Android SDK is different with the Android standard
4.4 Scene Priority
The valid value of scene priority is between 0 to 100.
Here is a list of the built-in settings.
Priority | Value |
SceneManager.SENCE_PRIORITY_MIN | 0 |
SceneManager.SENCE_PRIORITY_LOW | 20 |
SceneManager.SENCE_PRIORITY_MID | 40 |
SceneManager.SENCE_PRIORITY_HIGH | 60 |
SceneManager.SENCE_PRIORITY_EXTRA_HIGH | 80 |
SceneManager.SENCE_PRIORITY_MAX | 100 |
4.5 Built-in Scene
Scene | Priority | Purpose | Lifecycle |
Idle | 0 | Provide a default handle if there is no other scene | Always |
Launcher | 1 | The scene of the launcher app, which is used to handle dialing in the launcher. | From the launcher is displayed until the launcher is overwritten by another apps |
Media | 20 | The scene of playing media. | From the beginning of media paly until the media was ended or was interrupted by another scene. |
Commucation | 40 | The scene of making a conversation on a third-party app. | From the beginning of the conversation until it was ended or was interrupted by another scene. |
Voip Call | 80 | The scene of handling system VoIP call. | From the first VoIP call started until all calls stopped. |
Dialpad | 100 | The scene of handling dialpad event. | From the dialpad displayed until the exited the dialpad or was interrupted by another scene. |
5. Key Events
5.1 When app is running in foreground
When the app is running in foreground, the key events dispatching is the same as Android standard.
5.2 When app is running in background
When the app is running in background, the app should has its own SceneClinet with a high priority.
The key events will be sent to the Scene Client firstly, and then be send to the onUnhandleKeyEvent of the Scene Client.
5.3 Key Events list
public class KeyEvent {
public static final int KEYCODE_VOIP_REDIAL = KeyEvent.KEYCODE_VOIP_REDIAL;
public static final int KEYCODE_VOIP_FORWARD = KeyEvent.KEYCODE_VOIP_FORWARD;
public static final int KEYCODE_VOIP_HOLD = KeyEvent.KEYCODE_VOIP_HOLD;
public static final int KEYCODE_VOIP_SPEAKER = KeyEvent.KEYCODE_VOIP_SPEAKER;
public static final int KEYCODE_VOIP_HEADSET = KeyEvent.KEYCODE_VOIP_HEADSET;
public static final int KEYCODE_VOIP_TEAMS = KeyEvent.KEYCODE_VOIP_TEAMS;
public static final int KEYCODE_VOIP_MUTE = KeyEvent.KEYCODE_VOIP_MUTE;
public static final int KEYCODE_VOIP_OFFHOOK = KeyEvent.KEYCODE_VOIP_OFFHOOK;
public static final int KEYCODE_VOIP_ONHOOK = KeyEvent.KEYCODE_VOIP_ONHOOK;
public static final int KEYCODE_VOIP_MAILS = KeyEvent.KEYCODE_VOIP_MAILS;
public static final int KEYCODE_VOIP_VIDEO = KeyEvent.KEYCODE_VOIP_VIDEO;
public static final int KEYCODE_VOIP_USB_KEY = KeyEvent.KEYCODE_VOIP_USB_KEY;
public static final int KEYCODE_VOIP_BLUETOOTH_KEY = KeyEvent.KEYCODE_VOIP_BLUETOOTH_KEY;
public static final int KEYCODE_VOIP_WIFI_KEY = KeyEvent.KEYCODE_VOIP_WIFI_KEY;
public static final int KEYCODE_USBHEADSET_OFFHOOK = KeyEvent.KEYCODE_USBHEADSET_OFFHOOK;
public static final int KEYCODE_USBHEADSET_ONHOOK = KeyEvent.KEYCODE_USBHEADSET_ONHOOK;
public static final int KEYCODE_USBHEADSET_REDIAL = KeyEvent.KEYCODE_USBHEADSET_REDIAL;
public static final int KEYCODE_USBHEADSET_REJECT = KeyEvent.KEYCODE_USBHEADSET_REJECT;
public static final int KEYCODE_USBHEADSET_HOLD = KeyEvent.KEYCODE_USBHEADSET_HOLD;
}
6. LED
There are two types of LED on Htek Android phone.
Power LED, normally on the top of the phone.
Function key LED contains the Speaker, Headset, Voice Mail, Mute and so on.
6.1 Power LED Manager
The Power LED is aimed at showing the status of the phone. There are four different status now:
Ringing Status
Miss Call Status
Voice Message Status
Active Call Status
The PowerLEDManager is a system service, you can get the instance through this way:
PowerLEDManager ledManager = context.getSystemService(PowerLEDManager.class);
And here are the interfaces of the PowerLEDManager.
public class PowerLEDManager {
public void setInCall(boolean inCall);
public void setRinging(boolean on);
public void setExistMissCall(boolean has);
public void setHasVoiceMail(boolean has);
}
6.2 Function Key LED Manager
Function key contains the Speaker, Headset, Voice Mail, Mute and so on.
Different phone models may have different function keys. If you need the LED of a specific function key, please read the model datasheet, or consult Htek.
The manager of Function Key LED is LEDManager. It is also a system service and you can get the instance by the similar way:
LEDManager ledManager = context.getSystemService(LEDManager.class);
The interfaces of LEDManager lists as below:
public class LEDManager {
public void setMuteLedOn(boolean on)；
public void setHeadsetLedOn(boolean on);
public void setMailLedOn(boolean on);
public void setSpeakerLedOn(boolean on);
}
7. Audio Channel
The interfaces of controlling audio channel are contained in SceneManager. To get the instance of the SceneManger, you can do this:
SceneManager sceneManager = context.getSystemService(SceneManager.class);
The below content lists the interfaces related to audio channel controlling.
public class SceneManager {
/* Open handsfree */
public void openHandfree();
/* Open handset */
public void openHandset();
/* Open headset */
public void openHeadset();
/* The status of handset： true：off hook，false：on hook */
public boolean isHandsetOffHook();
/* The status of if the headset is high priority? true: yes; false: no */
public boolean isHeadsetFirstEnable();
/* Set the priority status of headset. */
public void setHeadsetFirstEnable(boolean enable);
/* The status of if the headset is enabled? */
public boolean isHeadsetOn();
/* The status of if the USB headset is enabled? */
public boolean isUSBHeadsetOn();
/* The status of if the BT headset is enabled? */
public boolean isBluetoothHeadsetOn();
/* The status of if the wired headset using RJ9 port if enabled? */
public boolean isWiredHeadsetOn();
/* The status of if the handset is enabled? */
public boolean isHandsetOn();
/* The status of if the handsfree is enabled? */
public boolean isHandfreeOn();
}
Note that even without registering your own SceneClient, you can still call the interfaces above. But if you want to get better embedded in the Htek Android phone and provide a better user experience, it is recommended to implement your own.
8. USB headset
The USBHeadsetManager is also a system service, you can get the instance through this way:
USBHeadsetManager usbHeadsetManager= context.getSystemService(USBHeadsetManager .class);
Then, you can control the USB headset by the below interfaces:
public class USBHeadsetManager {
/* mute headset mic */
public void setMicMuteOn(boolean on);
/* set headset hook status */
public void setHookStatus(boolean offHook);
/* set headset ringing */
public void setRinging(boolean ringing);
/* set headset hold */
public void setHold(boolean hold) ;
}
9. Default Dial App
In AndroidManifest.xml of the app, receive android.intent.action.DIAL and set the priority higher than 0, you can let the app become the default dial app.
Here is an example:
<activity
android:name=".MockDialerActivity"
android:exported="true">
<intent-filter android:priority="100">
<action android:name="android.intent.action.DIAL" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
<intent-filter android:priority="100">
<action android:name="android.intent.action.DIAL" />
<category android:name="android.intent.category.DEFAULT" />
<data android:scheme="tel" />
</intent-filter>
</activity>
10. Autostart
In AndroidManifest.xml of the app, receive android.intent.action.BOOT_COMPLETED.
Here is an example:
<receiver
android:name=".MockReceiver"
android:exported="true"
android:enabled="true">
<intent-filter>
<action android:name="android.intent.action.LOCKED_BOOT_COMPLETED" />
<action android:name="android.intent.action.BOOT_COMPLETED" />
<action android:name="android.intent.action.QUICKBOOT_POWERON" />
</intent-filter>
</receiver>
Htek SDK Demo
Date | Download Link | Revision |
|---|---|---|
| bc1277b5dd6b044f6bef82f03c1fcfec15f624bc | |