Android SDK

1. ASP Android SDK使用方法

1.1. 集成环境要求

最低支持Android版本：5.1

1.2. 主要文件

1.3. 示例 - 使用核心API

1.3.1. 通过maven repo二方包方式接入SDK

目前暂不支持

1.3.2. 以集成AAR包方式接入SDK

1. 将 aspengine-third-release.aar 拷贝到app/libs目录下。

2. 在应用模块的build.gradle加入：

dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
    // aspengine-sdk依赖的ini配置解析库
    implementation 'org.ini4j:ini4j:0.5.4'
}

3. AndroidManifest 声明必要的权限：

<uses-permission android:name="android.permission.INTERNET" />

4. AndroidManifest 配置Activity：

// 强制界面以横屏方式显示
<activity android:name=".ASPEngineDemoActivity" 
          android:launchMode="singleTop"
          android:screenOrientation="sensorLandscape">

1.3.3. 调用示例

public class ASPEngineDemoActivity extends Activity
        implements ICursorListener, IResolutionUpdateListener, IOrientationUpdateListener {
    static final String TAG = "MainActivity";

    private SurfaceView mAspSurfaceView = null;

    private ASPEngine.Builder mEngineBuilder = null;
    private IASPEngine mEngine = null;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        this.requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN, WindowManager.LayoutParams.FLAG_FULLSCREEN);

        setContentView(R.layout.activity_main);

        mAspSurfaceView = findViewById(R.id.asp_surface_view);
        
        // 监听touch消息并注入到ASPEngine
        mAspSurfaceView.setOnTouchListener(new View.OnTouchListener() {
            @Override
            public boolean onTouch(View view, MotionEvent motionEvent) {
                if (mEngine != null) {
                    return mEngine.sendTouchEvent(motionEvent);
                }
                return false;
            }
        });

        // 监听鼠标操作事件并注入到ASPEngine
        mAspSurfaceView.setOnGenericMotionListener(new View.OnGenericMotionListener(){
            @Override
            public boolean onGenericMotion(View v, MotionEvent motionEvent) {
                Log.d(TAG,String.format("mouse, onGenericMotion: %d", motionEvent.getSource()));
                if (0 != (motionEvent.getSource() & InputDevice.SOURCE_MOUSE)) {
                    if (mEngine != null) {
                        return mEngine.sendMouseEvent(motionEvent);
                    }
                }
                return true;
            }
        });

        // 创建Builder
        mEngineBuilder = new IASPEngine.Builder();
        
        // 创建ASPEngine对象
        mEngine = mEngineBuilder.build();
        
        // 设置Surface
        mEngine.setSurface(mAspSurfaceView);

        IASPEngineListener listener = new IASPEngineListener() {
            @Override
            public void onConnectionSuccess() {
                // server连接成功
                Log.i(TAG, "onConnectionSuccess");
            }

            @Override
            public void onConnectionFailure(int errorCode, String errorMsg) {
                // server连接失败
                Log.i(TAG, "onConnectionFailure errorCode:" + errorCode + " errorMsg:" + errorMsg);
            }

            @Override
            public void onEngineError(int errorCode, String errorMsg) {
                // ASPEngine内部发生错误
                Log.i(TAG, "onEngineError errorCode:" + errorCode + " errorMsg:" + errorMsg);
            }

            @Override
            public void onDisconnected(int reason) {
                // 连接已断开
                Log.i(TAG, "onDisconnected reason=" + reason);
            }

            @Override
            public void onReconnect() {
                // 发生重连
                Log.i(TAG, "onReconnect");
            }
        };

        // 监听连接及ASPEngine内部状态
        mEngine.registerASPEngineListener(listener);
        // 监听云端游标状态变化消息
        mEngine.registerCursorListener(this);
        // 监听云端分辨率变化消息
        mEngine.registerResolutionUpdateListener(this);
        // 监听云端屏幕旋转消息
        mEngine.registerOrientationUpdateListener(this);
    }
    
    /**
     * 用户登录成功后，通过无影OpenAPI接口获取对应云电脑的server session信息，并通过
     * 该方法启动ASPEngine.
     *
     * 登录及通过无影OpenAPI接口调用由应用开发者实现，相关接口使用方法请参考对应的文档
     *
     */
    protected void onGetServerSession(String session) {
        // 启动ASPEngine
        mEngine.start(session, null);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        if (mEngine != null) {
            mEngine.dispose();
            mEngine = null;
        }
    }

    @Override
    public boolean dispatchKeyEvent(KeyEvent event) {
        if (mEngine != null) {
            // 截获并注入键盘按键消息
            if (!mEngine.sendKeyboardEvent(event)) {
                return super.dispatchKeyEvent(event);
            }
            return true;
        }
        return super.dispatchKeyEvent(event);
    }
    
    /*
     * Cursor callback BEGIN
     * */
    @Override
    public void onCursorBitmapUpdate(int hotX, int hotY, int width, int height, byte[] rgba) {
        // 云上游标形态发生变化，将变化内容同步到本地游标
        Log.d(TAG,String.format("onCursorBitmapUpdate: hotX:%d, hotY:%d, width:%d, height:%d, len:%d :", hotX, hotY, width, height,rgba.length));
        //BitmapFactory.Options options = new BitmapFactory.Options();
        //options.inMutable = true;
        Bitmap rawBmp = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888);
        rawBmp.copyPixelsFromBuffer(ByteBuffer.wrap(rgba));
        if(rawBmp == null) {
            Log.i(TAG, "can't create cursor bitmap from rgba");
            return;
        }

        PointerIcon cursor = PointerIcon.create(rawBmp, hotX, hotY);
        mAspSurfaceView.setPointerIcon(cursor);
    }

    @Override
    public void onCursorHide()
    {
        // 云上游标被隐藏
        Log.i(TAG, "onCursorHide");
        PointerIcon cursor = PointerIcon.getSystemIcon(getApplicationContext(),PointerIcon.TYPE_NULL);
        mAspSurfaceView.setPointerIcon(cursor);
    }

    @Override
    public void onCursorReset() {
        // 云上游标被重置
        Log.i(TAG, "onCursorReset");
        PointerIcon cursor = PointerIcon.getSystemIcon(getApplicationContext(),PointerIcon.TYPE_DEFAULT);
        mAspSurfaceView.setPointerIcon(cursor);
    }

    @Override
    public void onCursorMove(int x, int y) {
        // 云上游标位置移动
    }
    /* Cursor callback END */

    @Override
    public void onResolutionUpdate(int oldWidth, int oldHeight, int width, int height) {
        // 云上分辨率发生变化，根据需要，端侧可以决定是否需要按照长宽比例对渲染内容进行scale
        Log.i(TAG, "onResolutionUpdate stream ow " + oldWidth + " oh " + oldHeight
                + " w " + width + " h " + height);
        Log.i(TAG, "current view width " + mAspSurfaceView.getWidth()
                + " height " + mAspSurfaceView.getHeight());

        float factorX = 1f;
        float factorY = 1f;

        float aspectRatio  = 1.0f * width / height;
        float viewAspectRatio = 1.0f * mAspSurfaceView.getWidth() / mAspSurfaceView.getHeight();
        Log.i(TAG, "StreamView aspect ratio " + viewAspectRatio
                + " VS remote window aspect ratio " + aspectRatio);
        // TODO: suppose current device orientation is landscape
        if (viewAspectRatio > aspectRatio) {
            // Align stream content with view height for landscape
            int expectedWidth = (int) (mAspSurfaceView.getHeight() * aspectRatio);
            Log.i(TAG, "Expect width " + expectedWidth);
            factorX = 1.0f * expectedWidth / mAspSurfaceView.getWidth();
        } else {
            // Align stream content with view width for portrait
            int expectedHeight = (int) (mAspSurfaceView.getWidth() / aspectRatio);
            Log.i(TAG, "Expect height " + expectedHeight);
            factorY = 1.0f * expectedHeight / mAspSurfaceView.getHeight();
        }

        Log.i(TAG, "Calculate scale factor x " + factorX + " y " + factorY);

        mAspSurfaceView.setScaleX(factorX);
        mAspSurfaceView.setScaleY(factorY);
    }

    @Override
    public void onOrientationUpdate(int oldOrientation, int newOrientation) {
        // 云上发生旋转屏幕的动作，客户端需要同步旋转屏幕并固定下来
        Log.i(TAG, "onOrientationUpdate from " + oldOrientation + " to " + newOrientation);
        switch (newOrientation) {
            case IOrientationUpdateListener.ORIENTATION_0:
            case IOrientationUpdateListener.ORIENTATION_180:
                setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT);
                break;
            case IOrientationUpdateListener.ORIENTATION_90:
                setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE);
                break;
            default:
                Log.i(TAG, "Unknown new orientation: " + newOrientation);
                break;
        }
    }
}

1.4. 示例 - 使用增强型UI组件

1.4.1. 以集成AAR包方式接入SDK

1. 将aspengine-thrid-release.aar拷贝到app/libs目录下。

2. 在应用模块的build.gradle加入：

dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
    // aspengine-sdk依赖的ini配置解析库
    implementation 'org.ini4j:ini4j:0.5.4'
}

3. AndroidManifest 声明必要权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.VIBRATE"/>

4. AndroidManifest 配置Activity：

// 强制界面以横屏方式显示
<activity android:name=".StreamViewDemoActivity" 
          android:launchMode="singleTop"
          android:screenOrientation="sensorLandscape">

5. layout配置：

<?xml version="1.0" encoding="utf-8"?>
<android.widget.RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".StreamViewDemoActivity">

    <com.aliyun.wuying.aspsdk.aspengine.ui.StreamView
        android:id="@+id/stream_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:focusableInTouchMode="true"
        android:focusable="true"
        android:focusedByDefault="true" />

</android.widget.RelativeLayout>

1.4.2 调用示例

public class StreamViewDemoActivity extends Activity {
    private static final String TAG = "StreamViewDemoActivity";
    private StreamView mStreamView = null;
    
    private IASPEngineListener mListener = new IASPEngineListener() {
        @Override
        public void onConnectionSuccess() {
            Log.i(TAG, "onConnectionSuccess");
        }
        @Override
        public void onConnectionFailure(int errorCode, String errorMsg) {
            Log.i(TAG, "onConnectionFailure errorCode:" + errorCode + " errorMsg:" + errorMsg);
        }
        @Override
        public void onEngineError(int errorCode, String errorMsg) {
            Log.i(TAG, "onEngineError errorCode:" + errorCode + " errorMsg:" + errorMsg);
        }1
        @Override
        public void onDisconnected(int reason) {
            Log.i(TAG, "onDisconnected reason=" + reason);
        }
        @Override
        public void onReconnect() {
            Log.i(TAG, "onReconnect");
        }
    };
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN, WindowManager.LayoutParams.FLAG_FULLSCREEN);

        setContentView(R.layout.activity_stream_view_demo);

        mStreamView = findViewById(R.id.stream_view);
        
        mStreamView.setASPEngineListener(mListener);
    }
    
    /**
     * 用户登录成功后，通过无影OpenAPI接口获取对应云电脑的server session信息，并通过
     * 该方法启动ASPEngine.
     *
     * 登录及通过无影OpenAPI接口调用由应用开发者实现，相关接口使用方法请参考对应的文档
     *
     */
    protected void onGetServerSession(String session) {
        // 开始ASP建连
        Bundle config = new Bundle();
        config.putString(StreamView.CONFIG_CONNECTION_TICKET, session);
        mStreamView.start(mConfigs);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        mStreamView.dispose();
        mStreamView = null;
    }
}

2. 接口定义及说明

2.1. IASPEngine.Builder

IASPEngine对象的构造器

2.1.1. Builder

构建一个IASPEngine的Builder

public Builder()

2.1.2. build

构建一个ASPEngine对象

public IASPEngine build()

返回值：

2.1.3. enableVDAagentCheck

建连时是否强制检查VDAgent的可用性，默认是进行检查。

当该值设置为True时，若在建连时发现VDAgent不可用，则会报错并断开当前连接。

不建议设置为false，通常只有在进行内部调试时才会这么做。

public IASPEngine.Builder enableVDAgentCheck(boolean enabled)

参数：

返回值：

2.1.4. enableRTC

设置是否使用RTC传输流化数据内容，默认使用RTC传输流化数据内容

public IASPEngine.Builder enableRTC(boolean enabled)

2.2. IASPEngine

IASPEngine是ASP Android SDK的核心接口，主要为应用提供以下几个方面的API：

• 提供串流控制接口，如启动/断开串流，暂停/恢复推流，设置鼠标server mode等

• 提供音视频设置接口，如视频分辨率，fps等

• 提供input事件向云端的注入接口

• 提供一系列regsiter方法用于注册监听SDK/云上各种状态的listener

2.2.1. start

通过从PaaS获取的server session启动串流服务，串流启动结果会通过IASPEngineListener回调返回给应用

public void start(String connectionTicket, String caFilePath)

参数：

2.2.2 start

通过指定的server连接参数启动云端的串流服务，串流启动结果会通过IASPEngineListener回调返回给应用

该方法通常用于日常调试，适用于不经过网关（或已知网关地址并得到可访问的token），能够直连ASP Server的情形

public void start(String host, String port, String udpPort, String caFilePath, String token, boolean enableTls)

参数：

2.2.3 stop

立即停止云端的串流服务，当连接断开时，应用可以通过IASPEngineListener回调得到连接断开的消息

public void stop()

2.2.4 pause

暂停云端的串流推流

public void pause(IRemoteResult result)

参数：

2.2.5 resume

恢复云端的串流推流

public void resume(IRemoteResult result)

参数：

2.2.6 enableStatistics

开启/关闭性能数据统计报告，报告会通过注册的IStatisticsListener返回

public void enableStatistics(boolean enable)

参数：

2.2.7 toggleServerCursorMode

开启/关闭云上光标模式（该方法未实现）

public void toggleServerCursorMode(boolean toggled)

参数：

2.2.8 setSurface

设置一个SurfaceView到ASPEngine。

ASPEngine在建立串流后，将通过设置的SurfaceView渲染流化图像。

void setSurface(SurfaceView surfaceView)

参数：

2.2.9 setVideoProfile

设置视频流的分辨率及帧率

目前fps参数不会生效

public void setVideoProfile(int width, int height, int fps, IRemoteResult result)

参数：

2.2.10 setImePreedit

当获取到本地输入法的预览文字后，通过该接口设置云上输入法需要显示的预览文字

该方法未实现

public void setImePreedit(String preeditStr, IRemoteResult result)

参数：

2.2.11 setImeCommit

当本地输入法的预览文字被提交到输入框中后，通过该接口设置云上输入法需要提交到输入框显示的文字

该方法未实现

public void setIMEPreedit(String commitStr, IRemoteResult result)

参数：

2.2.12 setKeyboardLockModifiers

设置键盘锁状态

该方法未实现

public void setKeyboardLockModifiers(int modifiers, IRemoteResult result)

参数：

2.2.13 registerASPEngineListener

注册IASPEngineListener，用于监听串流连接及运行错误状态

public void registerASPEngineListener(IASPEngineListener listener)

参数：

2.2.14 unregisterASPEngineListener

取消对串流连接及运行错误状态的监听

public void unregisterASPEngineListener(IASPEngineListener listener)

参数：

2.2.15 registerIMEListener

注册IIMEListener，用于监听云上输入框焦点获取及输入法UI位置状态

该方法未实现

public void registerIMEListener(IIMEListener listener)

参数：

2.2.16 unregisterIMEListener

取消对云上输入框焦点获取及输入法UI位置状态的监听

该方法未实现

public void unregisterIMEListener(IIMEListener listener)

参数：

2.2.17 registerAudioVolumeListener

注册IAudioVolumeListener，用于监听云上音量变化

该方法未实现

public void registerAudioVolumeListener(IAudioVolumeListener listener)

参数：

2.2.18 unregisterAudioVolumeListener

取消对云上音量变化的监听

该方法未实现

public void unregisterAudioVolumeListener(IAudioVolumeListener)

参数：

2.2.19 registerResolutionUpdateListener

注册IResolutionUpdateListener，用于监听视频流分辨率变化

public void registerResolutionUpdateListener(IResolutionUpdateListener listener)

参数：

2.2.20 unregisterResolutionUpdateListener

取消对视频流分辨率变化的监听

public void unregisterResolutionUpdateListener(IResolutionUpdateListener)

参数：

2.2.21 registerCursorListener

注册ICursorListener，用于监听云上光标的状态变化

public void registerCursorListener(ICursorListener listener)

参数：

2.2.22 unregisterCursorListener

取消对云上光标状态变化的监听

public void unregisterCursorListener(ICursorListener listener)

参数：

2.2.23 registerOrientationUpdateListener

注册IOrientationUpdateListener，用于监听云上屏幕旋转事件

public void registerOrientationUpdateListener(IOrientationUpdateListener listener)

参数：

2.2.24 unregisterOrientationUpdateListener

取消对云上屏幕旋转事件的监听

public void unregisterOrientationUpdateListener(IOrientationUpdateListener listener)

参数：

2.2.25 registerStatisticsListener

注册IStatisticsListener，用于监听性能及关键运行状态数据报告

public void registerStatisticsListener(IStatisticsListener listener)

参数：

2.2.26 unregisterStatisticsListener

取消对性能及关键运行状态数据报告的监听

public void unregisterStatisticsListener(IStatisticsListener listener)

参数：

2.2.27 sendTouchEvent

向云上发送Touch消息

public boolean sendTouchEvent(MotionEvent event)

参数：

返回值:

2.2.28 sendTouchEvent

向云上发送Touch消息，并异步返回发送结果

该方法未实现

public void sendTouchEvent(MotionEvent event, IRemoteResult result)

参数：

2.2.29 sendKeyboardEvent

向云上发送键盘按键消息

public boolean sendKeyboardEvent(KeyEvent event)

参数：

返回值:

2.2.30 sendKeyboardEvent

向云上发送键盘按键消息，并异步返回发送结果

该方法未实现

public void sendKeyboardEvent(KeyEvent event, IRemoteResult result)

参数：

2.2.31 sendMouseEvent

向云上发送鼠标按键消息

public boolean sendMouseEvent(MotionEvent motionEvent)

参数：

返回值:

2.2.32 sendMouseEvent

向云上发送鼠标按键消息，并异步返回发送结果

该方法未实现

public void sendMouseEvent(MotionEvent motionEvent, IRemoteResult result)

参数：

2.2.33 sendMouseEvent

向云上发送鼠标按键消息

public boolean sendMouseEvent(float x, float y, float axisValue, int action, int button, int state)

参数：

返回值:

2.2.34 sendGamePadConnected

向云上发送GamePad设备已连接的消息

该方法未实现

public boolean sendGamePadConnected(int id, int type)

参数：

返回值:

2.2.35 sendGamePadDisconnected

向云上发送GamePad设备断开连接的消息

该方法未实现

public boolean sendGamePadDisconnected(int id)

参数：

返回值:

2.2.36 sendGamePadEvent

向云上发送GamePad按键消息

该方法未实现

public boolean sendGamePadEvent(int id,String event)

参数：

返回值:

2.2.37 sendGamePadEvent

向云上发送GamePad按键消息，并异步返回发送结果

该方法未实现

public void sendGamePadEvent(String event, IRemoteResult result)

参数：

2.2.38 enableMouseMode

激活或关闭鼠标模式。

当鼠标模式激活时，会在屏幕呈现虚拟鼠标。

public boolean enableMouseMode(boolean enabled)

参数：

返回值:

2.2.39 enableDesktopMode

设置ASPEngine以桌面模式运行，设置为enabled后，ASPEngine会将所有Touch消息转换为Mouse事件向服务端发送。

public void enableDesktopMode(boolean enabled)

参数：

2.2.40 reconnect

发生连接异常断开时，可通过该接口执行重连动作。

通常针对disconnect reason=2200执行该动作，应用程序需要通过Open API重新获取连接云电脑的token并交给重连接口执行重连动作。

public void reconnect(String connectionToken)

参数：

2.2.41 dispose

断开与云电脑的连接并释放native资源，调用该方法后，ASPEngine对象处于不可用状态，应用逻辑不应再使用相同的对象执行任何串流相关操作

public void dispose()

2.2.42 setMediaStreamPlayer

使用应用自定义的媒体引擎替换SDK中默认的媒体引擎实现，该方法只能在发起串流之前，或串流断开之后调用。

boolean setMediaStreamPlayer(MediaStreamPlayer player);

返回值：

2.2.43 setAlignStreamResolutionWithSurfaceSize

设置是否在串流开始时，自动将流分辨率同步为端侧用于渲染图像的SurfaceView的大小，默认开启该功能。

void setAlignStreamResolutionWithSurfaceSize(boolean aligned);

2.2.44 registerRequestSystemPermissionListener

注册IRequestSystemPermissionListener，用于监听ASPEngine申请系统权限的请求。

public void registerRequestSystemPermissionListener(IRequestSystemPermissionListener listener)

参数：

2.2.45 unregisterRequestSystemPermissionListener

取消对ASPEngine申请系统权限请求的监听

public void unregisterRequestSystemPermissionListener(IRequestSystemPermissionListener listener)

参数：

2.2.46 mute

设置是否进入静音模式

void mute(boolean muted);

2.3 Listener

2.3.1 IRemoteResult

用于应用在使用异步设置/控制接口时，获取远程调用的响应结果：

onSuccess

当远程调用成功后，通过该方法告知应用。

某些流程云上可能没有执行成功的反馈，则以收到云上响应作为success标准

public void onSuccess()

onFailure

当远程调用失败时，通过该方法告知应用。

public void onFailure(int errorCode, String errorMsg)

参数：

onTimeout

当远程调用发生超时时，通过该方法告知应用。

public void onTimeout()

2.3.2 IASPEngineListener

用于监听串流连接的状态

onConnectionSuccess

当串流建连成功后，通过该方法告知应用

public void onConnectionSuccess()

onConnectionFailure

当串流建连失败，或连接状态发生异常，通过该方法告知应用

public void onConnectionFailure(int errorCode, String errorMsg)

参数：

onEngineError

ASPEngine内部逻辑发生异常时，如解码错误，内部状态错误等，通过该方法告知应用

public void onEngineError(int errorCode, String errorMsg)

参数：

onDisconnected

当连接断开时，通过该方法告知应用

public void onDisconnected(int reason)

参数：

onReconnect

当连接发生重连动作时，通过该方法告知应用

public void onReconnect()

2.3.3 IIMEListener

用于监听云上输入框焦点变化及输入法UI位置状态

onIMEFocusUpdate

当云上输入框获取/失去焦点时，通过该方法告知应用

public void onIMEFocusUpdate(boolean hasFocus)

参数：

onIMELocationUpdate

当云上输入法UI的位置发生变化时时，通过该方法告知应用

public void onIMELocationUpdate(int x, int y)

参数：

2.3.4 IAudioVolumeListener

用于监听云上系统的音量变化

onAudioVolumeUpdate

当云上系统的音量发生变化时，通过该方法告知应用

public void onAudioVolumeUpdate(double volume)

参数：

2.3.5 IResolutionUpdateListener

用于监听视频流的分辨率变化

onResolutionUpdate

当视频流的分辨率发生变化时，通过该方法告知应用

public void onResolutionUpdate(int oldWidth, int oldHeight, int width, int height)

参数：

2.3.6 ICursorListener

用于监听云上光标的状态变化，如光标形态变化，光变可见性变化等

onCursorBitmapUpdate

当云上光标形态变化时，通过该方法告知应用

public void onCursorBitmapUpdate(int hotX, int hotY, Bitmap bitmap)

参数：

onCursorReset

当云上光标状态被重置时，通过该方法告知应用

public void onCursorReset()

onCursorHide

当云上光标被隐藏时，通过该方法告知应用

public void onCursorHide()

onCursorMove

当云上光标位置发生变化时，通过该方法告知应用

public void onCursorMove(int x, int y)

参数：

2.3.7 IOrientationUpdateListener

用于监听云上屏幕旋转事件

onOrientationUpdate

当云上发生屏幕旋转事件时，通过该方法告知应用

public void onOrientationUpdate(int oldOrientation, int newOrientation)

参数：

2.3.8 IStatisticsListener

用于监听性能及关键运行状态数据报告

onStatisticsInfoUpdate

若应用调用了enableStatistics，则ASPEngine会定期更新性能及关键运行状态数据报告，并通过该方法告知应用

public void onStatisticsInfoUpdate(StatisticsInfo info)

参数：

StatisticsInfo

class StatisticsInfo {
   public int mReceiveFps = 0; // 端侧每秒接收到的视频祯数量
   public int mRenderFps = 0; // 端侧渲染FPS
   public double mDownstreamBandwithMBPerSecond = 0; // 下行带宽，MB/s
   public double mUpstreamBandwithMBPerSecond = 0; // 上行带宽，MB/s
   public long mP2pFullLinkageLatencyMS = -1; // 端到端全链路时延，毫秒
   // 目前该值需要在guest os中使用特定应用才可准确表示
   public long mNetworkLatencyMS = -1; // 网络rtt时延，毫秒
   public double mLostRate = 0; // 丢包率
   public long mServerRenderLatencyMS = -1; // 服务端渲染时延，毫秒
   public long mServerEncoderLatencyMS = -1; // 服务端编码时延，毫秒
   public long mServerTotalLatencyMS = -1; // 服务端总时延，毫秒
}

2.3.9. IRequestSystemPermissionListener

用于监听ASPEngine申请系统全新的请求

onRequestSystemPermission

当ASPEngine需要申请某个系统权限时，通过该方法告知应用。

public void onRequestSystemPermission(SystemPermission permission)

参数：

SystemPermission

enum SystemPermission {
    RECORD_AUDIO; // 录音权限
}

2.3.10 IExtDeviceListener

用于监听存储设备或摄像头等设备的连接变化

 /**
 * 当存储设备连接或断开连接时回调
 * @param udisks 存储设备列表
 */
void onUDisksUpdate(List<UDiskItem> udisks);

/**
 * 当摄像头设备连接或者断开连接时回调
 * @param cameras 摄像头设备列表
 */
void onCamerasUpdate(List<CameraItem> cameras);

设备控制：

当获取到设备列表后，可以通过以下接口单独控制某设备

UDiskItem类设备控制

/**
 * 获取当前设备连接状态
 * @return ConnectStatus.DISCONNECTED: 未连接状态 ConnectStatus.CONNECTED: 连接状态
 */
ConnectStatus getStatus();

/**
 * 获取当前设备名称
 * @return 设备名称
 */
String getName();

/**
 * 获取存储路径
 * @return 存储路径
 */
String getPath();

/**
 * 连接设备
 */
void connect();
/**
 * 断开设备
 */
void disConnect();

CameraItem类设备控制

/**
 * 获取当前设备连接状态
 * @return ConnectStatus.DISCONNECTED: 未连接状态 ConnectStatus.CONNECTED: 连接状态
 */
ConnectStatus getStatus();

/**
 * 获取当前设备名称
 * @return 设备名称
 */
String getName();

/**
 * 连接设备
 */
void connect();

/**
 * 断开设备
 */
void disConnect();

/**
 * 获取是否预览镜像
 */
boolean isPreviewMirror();

/**
 * 设置预览镜像
 */
void setPreviewMirror(boolean mirror);

2.4 Static方法

2.4.1 IASPEngine.setLogAdapter

设置一个全局的LoggerAdapter对象，应用程序通过继承并实现LoggerAdapter定义的抽象方法实现Log重定向功能

public static void setLogAdapter(LoggerAdapter logAdapter)

参数：

LoggerAdapter

public interface LoggerAdapter {
    public void onLogMessage(String tag, String msg, LogLevel level);
}

2.5 StreamView

StreamView是一个RelativeLayout容器，其子view至少包含一个SurfaceView用于渲染流化图像。

StreamView内部集成了ASPEngine，并实现了对ASP流的控制及input注入，事件提示等功能，通过StreamView，应用程序能够更快速地集成ASP的相关能力。

2.5.1 配置常量名

2.5.2 start

根据指定配置项启动串流流程。

public void start(Bundle configs)

参数：

2.5.3 stop

立即停止云端的串流服务

public void stop()

2.5.4 dispose

立即停止云端的串流服务并重置StreamView内部状态，activity在接收到onDestroy消息时需要调用该方法

public void dispose()

2.5.5 scaleStreamVideo

StreamView根据指定的策略对流化图像内容进行相应的缩放处理

public void scaleStreamVideo(ScaleType scaleType)

参数：

2.5.6 enableDesktopMode

设置StreamView以桌面模式运行，设置为enabled后，StreamView会将所有Touch消息转换为Mouse事件向服务端发送。

public void enableDesktopMode(boolean enabled)

参数：

2.5.7 setASPEngineListener

注册IASPEngineListener，用于监听串流连接及运行错误状态

public void registerASPEngineListener(IASPEngineListener listener)

参数：

2.5.8 setVideoProfile

设置视频流的分辨率及帧率

目前fps参数不会生效

public void setVideoProfile(int width, int height, int fps, IRemoteResult result)

参数：

2.5.9 sendKeyEvent

向云上发送键盘按键消息

public boolean sendKeyEvent(KeyEvent event)

参数：

返回值:

2.5.10 simulateMouseClick

模拟向云上发送鼠标点击事件

参数：

2.5.11 getASPEngineDelegate

获取StreamView内部IASPEngine实例的代理对象

public ASPEngineDelegate getASPEngineDelegate()

返回值:

2.5.12 ASPEngineDelegate

ASPEngineDelegate是IASPEngine实例的代理类，StreamView通过该类向外暴露部分IASPEngine接口。

应用程序可通过StreamView.getASPEngineDelegate获取该类的实例。

2.5.12.1 registerASPEngineListener

注册IASPEngineListener，用于监听串流连接及运行错误状态

public void registerASPEngineListener(IASPEngineListener listener)

参数：

2.5.12.2 unregisterASPEngineListener

取消对串流连接及运行错误状态的监听

public void unregisterASPEngineListener(IASPEngineListener listener)

参数：

2.5.12.3 registerStatisticsListener

注册IStatisticsListener，用于监听性能及关键运行状态数据报告

public void registerStatisticsListener(IStatisticsListener listener)

参数：

2.5.12.4 unregisterStatisticsListener

取消对性能及关键运行状态数据报告的监听

public void unregisterStatisticsListener(IStatisticsListener listener)

参数：

2.5.12.5 enableMouseMode

激活或关闭鼠标模式

public boolean enableMouseMode(boolean enabled)

参数：

返回值:

2.5.12.6 setVideoProfile

设置视频流的分辨率及帧率

public void setVideoProfile(int width, int height, int fps, IRemoteResult result)

参数：

2.5.12.7 sendKeyboardEvent

向云上发送键盘按键消息

public boolean sendKeyboardEvent(KeyEvent event)

参数：

返回值:

2.5.12.8 sendKeyboardEvent

向云上发送键盘按键消息，并异步返回发送结果

该方法未实现

public void sendKeyboardEvent(KeyEvent event, IRemoteResult result)

参数：

2.5.12.9 sendMouseEvent

向云上发送鼠标按键消息

public boolean sendMouseEvent(MotionEvent motionEvent)

参数：

返回值:

2.5.12.10 sendMouseEvent

向云上发送鼠标按键消息，并异步返回发送结果

该方法未实现

public void sendMouseEvent(MotionEvent motionEvent, IRemoteResult result)

参数：

2.5.12.11 enableDesktopMode

设置ASPEngine以桌面模式运行，设置为enabled后，ASPEngine会将所有Touch消息转换为Mouse事件向服务端发送。

public void enableDesktopMode(boolean enabled)

参数：

2.5.12.12 reconnect

发生连接异常断开时，可通过该接口执行重连动作。

通常针对disconnect reason=2200执行该动作，应用程序需要通过Open API重新获取连接云电脑的token并交给重连接口执行重连动作。

public void reconnect(String connectionToken)

参数：

2.5.12.13 setMediaStreamPlayer

使用应用自定义的媒体引擎替换SDK中默认的媒体引擎实现，该方法只能在发起串流之前，或串流断开之后调用。

boolean setMediaStreamPlayer(MediaStreamPlayer player);

返回值:

2.5.12.14 setAlignStreamResolutionWithSurfaceSize

设置是否在串流开始时，自动将流分辨率同步为端侧用于渲染图像的SurfaceView的大小，默认开启该功能。

void setAlignStreamResolutionWithSurfaceSize(boolean aligned);

2.5.12.15 registerRequestSystemPermissionListener

注册 IRequestSystemPermissionListener，用于监听ASPEngine申请系统权限的请求。

public void registerRequestSystemPermissionListener(IRequestSystemPermissionListener listener)

参数：

2.5.12.16 unregisterRequestSystemPermissionListener

取消对ASPEngine申请系统权限请求的监听

public void unregisterRequestSystemPermissionListener(IRequestSystemPermissionListener listener)

参数：

2.5.12.17 mute

设置是否进入静音模式

void mute(boolean muted);

2.5.12.18 setToQualityFirst

设置画质优先模式，该模式下所支持的最高帧率为 30 FPS，最高画质为优质

/**
 * 设置画质优先模式，该模式下所支持的最高帧率为 30 FPS，最高画质为优质
 */
void setToQualityFirst();

2.5.12.19 setToFpsFirst

设置流畅优先模式，该模式下所支持最高帧率为 60 FPS，最高画质为良好

/**
 * 设置流畅优先模式，该模式下所支持最高帧率为 60 FPS，最高画质为良好
 */
void setToFpsFirst();

2.5.12.20 setToCustomPicture

用户自定义模式，用户可以自定义帧率和画质

 /**
  * 用户自定义模式，用户可以自定义帧率和画质
  * @param fps 值为 0 到 60 区间，代表帧率设置，值越高越流畅
  * @param quality 值为 0 到 4 区间，0：无损，1：优质 2：良好 3：一般 4：自动
  */
void setToCustomPicture(int fps, int quality);

2.5.12.21 enableStatistics

设置状态检测是否可用

void enableStatistics(boolean enabled);

3. 使用自定义媒体引擎处理媒体数据

通过实现com.aliyun.wuying.aspsdk.aspengine.MediaStreamPlayer，应用程序可使用自定义的媒体引擎处理串流媒体数据，这些数据主要包括：

• 视频流数据 - 以H264/H265压缩帧为主的视频裸流

• 自适应图片流数据 - 以位图为主的图像流

• 音频下行数据 - 以Opus/PCM为主的音频下行数据流

• 光标数据 - 启用虚拟鼠标模式时，应用程序可接收到光标图像及位置数据，应用程序可使用这些数据自行绘制虚拟光标

应用程序可以通过调用IASPEngine.setMediaStreamPlayer接口向无影SDK提供自定以的媒体引擎实现。

3.1 MediaStreamPlayer

MediaStreamPlayer是一个抽象类，它要求应用程序实现全局的初始化/销毁方法，并提供处理不同媒体数据的自定义实现：

其中：

• IVideoStreamHandler接口定义了用于处理视频流数据的方法

• IAdaptiveGraphicStreamHandler接口定义了用于处理自适应图片流数据的方法

• IAudioPlaybackStreamHandler接口定义了用于处理音频下行数据的方法

• ICursorBitmap接口定义了用于处理光标数据的方法

应用程序可自行选择实现上述接口中的一个或多个，无影SDK最终会根据应用程序提供的接口实现设置云上下发流的类型，规则如下：

• 若应用程序同时提供了IVideoStreamHandler及IAdaptiveGraphicStreamHandler的实现，则串流被设置为混合模式，无影将根据当前使用的场景自动在自适应图片流及视频流之间进行切换

• 若应用程序仅提供IVideoStreamHandler的实现，则串流将被设置为Video stream only，此时服务端只会提供视频流数据

• 若应用程序仅提供IAudioPlaybackStreamHandler的实现，则串流将被设置为Image stream only，此时服务端只会提供图片流数据

应用程序可通过实现MediaStreamPlayer的一系列onCreateXXXHandler方法向SDK提供针对不同媒体数据的自定义实现：

    @Override
    protected IVideoStreamHandler onCreateVideoStreamHandler() {
        return new VideoStreamHandler();
    }

    @Override
    protected IAdaptiveGraphicStreamHandler onCreateAdaptiveGraphicStreamHandler() {
        return null;
    }

    @Override
    protected IAudioPlaybackStreamHandler onCreateAudioPlaybackStreamHandler() {
        return new AudioPlaybackStreamHandler();
    }

    @Override
    protected ICursorBitmapHandler onCreateCursorBitmapHandler() {
        return null;
    }

在上面的例子中，自定义媒体引擎提供了IVideoStreamHandler及IAudioPlaybackStreamHandler的实现，onCreateXXXHandler方法在一次串流过程中只会被执行一次。

主要方法调用流程：

3.1.1 initialize

由应用程序实现该方法，可用于执行自定义媒体引擎相关的全局初始化动作。

该方法在每次串流过程中将被执行一次。

public ErrorCode initialize()

返回值:

3.1.2 release

由应用程序实现该方法，可用于执行自定义媒体引擎相关的全局释放动作。

该方法在每次串流过程中将被执行一次。

public ErrorCode release()

返回值:

3.1.3 enableStatistics

由应用程序实现该方法，可用于激活/关闭性能统计数据采集。

public void enableStatistics(boolean enabled)

参数：

3.1.4 onCreateVideoStreamHandler

由应用程序实现该方法，用于向SDK提供处理视频流数据的媒体引擎实现。

该方法在每次串流过程中将被执行一次。

public IVideoStreamHandler onCreateVideoStreamHandler()

返回值:

3.1.5 onCreateAdaptiveGraphicStreamHandler

由应用程序实现该方法，用于向SDK提供处理自适应图片流数据的媒体引擎实现。

该方法在每次串流过程中将被执行一次。

public IAdaptiveGraphicStreamHandler onCreatAdaptiveGraphicStreamHandler()

返回值:

3.1.6 onCreateAudioPlaybackStreamHandler

由应用程序实现该方法，用于向SDK提供处理音频下行数据的媒体引擎实现。

该方法在每次串流过程中将被执行一次。

public IAudioPlaybackStreamHandler onCreatAudioPlaybackStreamHandler()

返回值:

3.1.7 onCreateCursorBitmapHandler

由应用程序实现该方法，用于向SDK提供处理光标数据的媒体引擎实现。

该方法在每次串流过程中将被执行一次。

通过该方法提供的接口实现仅在虚拟鼠标模式激活时被使用。

public ICursorBitmapHandler onCreatCursorBitmapHandler()

返回值:

3.2 IVideoStreamHandler

该接口定义了处理视频流数据的主要方法，其主要工作流程如下：

当应用发生前后台切换时，用于渲染的Surface将被销毁或重建，在这种情况下，IVideoStreamHandler.setVideoSurface将被多次调用，当Surface被销毁时，通过setVideoSurface传入的surface对象为null，应用程序需要处理好decoder及render的容错工作。

应用程序通过实现IVideoStreamHandler.setEventHandler方法可获取无影SDK提供的事件处理接口，通过该接口，应用程序可以将自定义媒体引擎内的一些视频处理事件通知给无影SDK内部，目前主要用于性能数据统计：

    @Override
    public void setEventHandler(EventHandler handler) {
        Log.i(TAG, "setEventHandler handler " + handler);
        VideoStreamEventHandler.getInstance().reset(handler);
    }

...
    
    public synchronized void onVideoFrameRendered() {
        VFrame frame = mVideoFrame.remove();
        if (mEnabled && mHandler != null) {
            Event event = new Event();
            event.type = EventType.RENDER_PERF_INFO;
            event.decodePerfInfo = new VDecodePerfInfo();
            event.renderPerfInfo = new VRenderPerfInfo();
            event.renderPerfInfo.frameId = frame.frameId;
            event.renderPerfInfo.sessionId = frame.sessionId;
            // 通知无影SDK一帧视频图像完成渲染，SDK内部根据frameId计算端侧全链路时延
            mHandler.callback(event);
        }
    }

3.2.1 setEventHandler

由应用程序实现该方法，当自定义媒体引擎被无影SDK加载时，SDK通过该方法向应用程序提供EventHandler，应用程序可通过该handler发送视频流处理事件。

public void setEventHandler(EventHandler handler)

参数：

3.2.2 addVideoTrack

由应用程序实现该方法，当一路视频流创建时，通过该方法通知应用程序。

目前一次串流过程中最多只存在一路视频。

ErrorCode addVideoTrack(int trackId, VProfile profile);

参数：

返回值:

3.2.3 setVideoSurface

由应用程序实现该方法，当用于渲染视频的Surface状态发生变化时，通过该方法通知应用程序。

ErrorCode setVideoSurface(int trackId, Surface surface);

参数：

返回值:

3.2.4 playVideo

由应用程序实现该方法，当用视频流准备就绪时，通过该方法通知应用程序。

ErrorCode playVideo(int trackId);

参数：

返回值:

3.2.5 removeVideoTrack

由应用程序实现该方法，当视频流被销毁时，通过该方法通知应用程序。

ErrorCode removeVideoTrack(int trackId);

参数：

返回值:

3.2.6 pushVideoFrame

由应用程序实现该方法，当用于接收到新的视频帧时，通过该方法通知应用程序。

ErrorCode setVideoSurface(int trackId, Surface surface);

参数：

返回值:

3.2.7 getVideoTracks

由应用程序实现该方法，SDK通过该方法从应用程序获取当前正在处理所有视频流信息。

HashMap<Integer, VProfile> getVideoTracks();

返回值:

3.2.8 release

由应用程序实现该方法，当所有的视频流被销毁时，通过该方法通知应用程序执行清理动作。

ErrorCode release();

返回值:

3.3 IAudioPlaybackStreamHandler

该接口定义了处理音频流数据的主要方法，其主要工作流程如下：

3.3.1 initAudio

由应用程序实现该方法，当SDK内的音频通道创建时，通过该方法通知应用程序。

ErrorCode initAudio();

返回值:

3.3.2 deInitAudio

由应用程序实现该方法，当SDK内的音频通道被销毁时，通过该方法通知应用程序。

ErrorCode deInitAudio();

返回值:

3.3.3 startAudioPlayback

由应用程序实现该方法，当云电脑将要开始下发音频流时，通过该方法通知应用程序。

ErrorCode startAudioPlayback();

返回值:

3.3.4 stopAudioPlayback

由应用程序实现该方法，当云电脑停止下发音频流时，通过该方法通知应用程序。

ErrorCode stopAudioPlayback();

返回值:

3.3.5 pushAudioPlaybackFrame

由应用程序实现该方法，当接收到新的下行音频帧时，通过该方法通知应用程序。

ErrorCode pushAudioPlaybackFrame(AFrame pbData);

参数：

返回值:

3.3.6 updateAudioPlaybackVol

由应用程序实现该方法，当云电脑里的系统音量大小发生变化时，通过该方法通知应用程序。

ErrorCode updateAudioPlaybackVol(int volume);

参数：

返回值:

3.3.7 updateAudioPlaybackMute

由应用程序实现该方法，当云电脑被静音/解除静音时，通过该方法通知应用程序。

ErrorCode updateAudioPlaybackMute(int mute);

参数：

返回值:

3.3.8 release

由应用程序实现该方法，当音频通道被销毁时，通过该方法通知应用程序执行清理动作。

ErrorCode release();

返回值:

3.4 IAdaptiveGraphicStreamHandler

该接口定义了处理图像流数据的主要方法，其主要工作流程如下：

目前应用程序获取到的图片帧格式为位图ARGB8888。

一次串流过程中最多存在一个图片流。

3.4.1 setAdaptiveGraphicSurface

由应用程序实现该方法，当用于渲染图片的Surface状态发生变化时，通过该方法通知应用程序

ErrorCode setAdaptiveGraphicSurface(Surface surface);

参数：

返回值:

3.4.2 invalidateAdaptiveGraphicSurface

由应用程序实现该方法，当用于接收到新的图片帧数据时，通过该方法通知应用程序

ErrorCode invalidateAdaptiveGraphicSurface(Region region, byte[] buffer, BitmapFormat format);

参数：

返回值:

3.4.3 release

由应用程序实现该方法，当图片流被销毁时，通过该方法通知应用程序执行清理动作。

ErrorCode release();

返回值:

3.5 ICursorBitmapHandler

该接口定义了处理光标数据的主要方法，在虚拟鼠标模式激活时，应用程序向SDK提供该接口的实现用于光标图像的绘制，其主要工作流程如下：

3.5.1 setCursorBitmap

由应用程序实现该方法，当云电脑里的光标形状生变化时，通过该方法通知应用程序。

ErrorCode setCursorBitmap(CursorBitmap bitmap);

参数：

返回值:

3.5.2 unsetCursorBitmap

由应用程序实现该方法，当云电脑里的光标被隐藏时，通过该方法通知应用程序。

ErrorCode unsetCursorBitmap();

返回值:

3.5.3 setCursorPosition

由应用程序实现该方法，当云电脑里的光标形状生变化时，通过该方法通知应用程序。

ErrorCode setCursorPosition(float x, float y);

参数：

返回值：

3.5.4 release

由应用程序实现该方法，当连接断开，取消光标显示时，通过该方法通知应用程序执行清理动作。

ErrorCode release();

返回值：

4. 附件

4.1 demo

AndroidDemo.zip

4.2 sdk

AndroidSDK.aar.zip