Android Audio代码分析24 - AudioEffect::setEnabled函数

之前已经看过，通过接口getEnabled可以取得effect的enable状态。
今天来看看如何来改变enable状态。


*****************************************源码*************************************************

    //Test case 2.0: test setEnabled() and getEnabled() in valid state
    @LargeTest
    public void test2_0SetEnabledGetEnabled() throws Exception {
        boolean result = false;
        String msg = "test2_0SetEnabledGetEnabled()";


        try {
            AudioEffect effect = new AudioEffect(AudioEffect.EFFECT_TYPE_EQUALIZER,
                    AudioEffect.EFFECT_TYPE_NULL,
                    0,
                    0);
            assertNotNull(msg + ": could not create AudioEffect", effect);
            try {
                effect.setEnabled(true);
                assertTrue(msg + ": invalid state from getEnabled", effect.getEnabled());
                effect.setEnabled(false);
                assertFalse(msg + ": invalid state to getEnabled", effect.getEnabled());
                result = true;
            } catch (IllegalStateException e) {
                msg = msg.concat(": setEnabled() in wrong state");
            } finally {
                effect.release();
            }
        } catch (IllegalArgumentException e) {
            msg = msg.concat(": Equalizer not found");
            loge(msg, ": Equalizer not found");
        } catch (UnsupportedOperationException e) {
            msg = msg.concat(": Effect library not loaded");
            loge(msg, ": Effect library not loaded");
        }
        assertTrue(msg, result);
    }

**********************************************************************************************
源码路径：
frameworks\base\media\tests\mediaframeworktest\src\com\android\mediaframeworktest\functional\MediaAudioEffectTest.java


#######################说明################################

    //Test case 2.0: test setEnabled() and getEnabled() in valid state
    @LargeTest
    public void test2_0SetEnabledGetEnabled() throws Exception {
        boolean result = false;
        String msg = "test2_0SetEnabledGetEnabled()";


        try {
            AudioEffect effect = new AudioEffect(AudioEffect.EFFECT_TYPE_EQUALIZER,
                    AudioEffect.EFFECT_TYPE_NULL,
                    0,
                    0);
            assertNotNull(msg + ": could not create AudioEffect", effect);
            try {
                effect.setEnabled(true);
// ++++++++++++++++++++++++++++++setEnabled++++++++++++++++++++++++++++++++++
    /**
     * Enable or disable the effect.
     * Creating an audio effect does not automatically apply this effect on the audio source. It
     * creates the resources necessary to process this effect but the audio signal is still bypassed
     * through the effect engine. Calling this method will make that the effect is actually applied
     * or not to the audio content being played in the corresponding audio session.
     *
     * @param enabled the requested enable state
     * @return {@link #SUCCESS} in case of success, {@link #ERROR_INVALID_OPERATION}
     *         or {@link #ERROR_DEAD_OBJECT} in case of failure.
     * @throws IllegalStateException
     */
// 创建一个audio effect，它并不会自发发挥作用。
// 该函数可以启动/停止该audio effect发挥作用。
    public int setEnabled(boolean enabled) throws IllegalStateException {
        checkState("setEnabled()");
        return native_setEnabled(enabled);
// ++++++++++++++++++++++++++++++android_media_AudioEffect_native_setEnabled++++++++++++++++++++++++++++++++++
static jint
android_media_AudioEffect_native_setEnabled(JNIEnv *env, jobject thiz, jboolean enabled)
{
    // retrieve the AudioEffect object
    AudioEffect* lpAudioEffect = (AudioEffect *)env->GetIntField(
        thiz, fields.fidNativeAudioEffect);


    if (lpAudioEffect == NULL) {
        jniThrowException(env, "java/lang/IllegalStateException",
            "Unable to retrieve AudioEffect pointer for enable()");
        return AUDIOEFFECT_ERROR_NO_INIT;
    }


    return translateError(lpAudioEffect->setEnabled(enabled));
// ++++++++++++++++++++++++++++++AudioEffect::setEnabled++++++++++++++++++++++++++++++++++
status_t AudioEffect::setEnabled(bool enabled)
{
    if (mStatus != NO_ERROR) {
        return INVALID_OPERATION;
    }


    if (enabled) {
        LOGV("enable %p", this);
        if (android_atomic_or(1, &mEnabled) == 0) {
// mIEffect的赋值在函数AudioEffect::set中。
//    iEffect = audioFlinger->createEffect(getpid(), (effect_descriptor_t *)&mDescriptor,
//            mIEffectClient, priority, output, mSessionId, &mStatus, &mId, &enabled);
//    mIEffect = iEffect;


// 函数AudioFlinger::createEffect中，调用了函数AudioFlinger::PlaybackThread::createEffect_l来创建一个对象并将其返回。
        // create effect on selected output trhead
//        handle = thread->createEffect_l(client, effectClient, priority, sessionId,
//                &desc, enabled, &lStatus);


// 函数AudioFlinger::PlaybackThread::createEffect_l中创建了一个EffectHandle对象并将其返回
        // create effect handle and connect it to effect module
//        handle = new EffectHandle(effect, client, effectClient, priority);
//        lStatus = effect->addHandle(handle);


// 所以，此处调用的其实是函数AudioFlinger::EffectHandle::enable。
           return mIEffect->enable();
// +++++++++++++++++++++++++++++AudioFlinger::EffectHandle::enable+++++++++++++++++++++++++++++++++++
status_t AudioFlinger::EffectHandle::enable()
{
    if (!mHasControl) return INVALID_OPERATION;
    if (mEffect == 0) return DEAD_OBJECT;


    return mEffect->setEnabled(true);
// +++++++++++++++++++++++++++++AudioFlinger::EffectModule::setEnabled+++++++++++++++++++++++++++++++++++
status_t AudioFlinger::EffectModule::setEnabled(bool enabled)
{
    Mutex::Autolock _l(mLock);
    LOGV("setEnabled %p enabled %d", this, enabled);


    if (enabled != isEnabled()) {
        switch (mState) {
        // going from disabled to enabled
        case IDLE:
            mState = STARTING;
            break;
        case STOPPED:
            mState = RESTART;
            break;
        case STOPPING:
            mState = ACTIVE;
            break;


        // going from enabled to disabled
        case RESTART:
            mState = STOPPED;
            break;
        case STARTING:
            mState = IDLE;
            break;
        case ACTIVE:
            mState = STOPPING;
            break;
        }
        for (size_t i = 1; i < mHandles.size(); i++) {
// 函数AudioFlinger::PlaybackThread::createEffect_l中创建了一个EffectHandle对象后，
// 会调用函数AudioFlinger::EffectModule::addHandle将其添加到mHandles中。
            sp<EffectHandle> h = mHandles[i].promote();
            if (h != 0) {
// 因此，此处调用的是函数AudioFlinger::EffectHandle::setEnabled。
                h->setEnabled(enabled);
// ++++++++++++++++++++++++++++AudioFlinger::EffectHandle::setEnabled++++++++++++++++++++++++++++++++++++
void AudioFlinger::EffectHandle::setEnabled(bool enabled)
{
// mEffectClient在AudioFlinger::EffectHandle::EffectHandle的构造函数中被赋值
// 该client对象最初在函数AudioEffect::set中被创建：mIEffectClient = new EffectClient(this);
// 接着传给了函数AudioFlinger::createEffect，接着到函数AudioFlinger::PlaybackThread::createEffect_l，
// 最终到了AudioFlinger::EffectHandle::EffectHandle的构造函数。
    if (mEffectClient != 0) {
        mEffectClient->enableStatusChanged(enabled);
// ++++++++++++++++++++++++++++EffectClient::enableStatusChanged++++++++++++++++++++++++++++++++++++
        virtual void enableStatusChanged(bool enabled) {
// mEffect在 EffectClient 的构造函数中被赋值， 
// 所赋值在函数 AudioEffect::set 中传入 ： mIEffectClient = new EffectClient(this);
// 所以，此处调用的是函数 AudioEffect::enableStatusChanged
            mEffect->enableStatusChanged(enabled);
// ++++++++++++++++++++++++++++AudioEffect::enableStatusChanged++++++++++++++++++++++++++++++++++++
void AudioEffect::enableStatusChanged(bool enabled)
{
    LOGV("enableStatusChanged %p enabled %d mCbf %p", this, enabled, mCbf);
    if (mStatus == ALREADY_EXISTS) {
        if (enabled) {
            android_atomic_or(1, &mEnabled);
        } else {
            android_atomic_and(~1, &mEnabled);
        }
        if (mCbf) {
// 此处其实是调用的函数 effectCallback
            mCbf(EVENT_ENABLE_STATUS_CHANGED, mUserData, &enabled);
// +++++++++++++++++++++++++++++effectCallback+++++++++++++++++++++++++++++++++++
static void effectCallback(int event, void* user, void *info) {


    effect_param_t *p;
    int arg1 = 0;
    int arg2 = 0;
    jobject obj = NULL;
    jbyteArray array = NULL;
    jbyte *bytes;
    bool param;
    size_t size;


    effect_callback_cookie *callbackInfo = (effect_callback_cookie *)user;
    JNIEnv *env = AndroidRuntime::getJNIEnv();


    LOGV("effectCallback: callbackInfo %p, audioEffect_ref %p audioEffect_class %p",
            callbackInfo,
            callbackInfo->audioEffect_ref,
            callbackInfo->audioEffect_class);


    if (!user || !env) {
        LOGW("effectCallback error user %p, env %p", user, env);
        return;
    }


    switch (event) {
    case AudioEffect::EVENT_CONTROL_STATUS_CHANGED:
        if (info == 0) {
            LOGW("EVENT_CONTROL_STATUS_CHANGED info == NULL");
            goto effectCallback_Exit;
        }
        param = *(bool *)info;
        arg1 = (int)param;
        LOGV("EVENT_CONTROL_STATUS_CHANGED");
        break;
    case AudioEffect::EVENT_ENABLE_STATUS_CHANGED:
        if (info == 0) {
            LOGW("EVENT_ENABLE_STATUS_CHANGED info == NULL");
            goto effectCallback_Exit;
        }
        param = *(bool *)info;
        arg1 = (int)param;
        LOGV("EVENT_ENABLE_STATUS_CHANGED");
        break;
    case AudioEffect::EVENT_PARAMETER_CHANGED:
        if (info == 0) {
            LOGW("EVENT_PARAMETER_CHANGED info == NULL");
            goto effectCallback_Exit;
        }
        p = (effect_param_t *)info;
        if (p->psize == 0 || p->vsize == 0) {
            goto effectCallback_Exit;
        }
        // arg1 contains offset of parameter value from start of byte array
        arg1 = sizeof(effect_param_t) + ((p->psize - 1) / sizeof(int) + 1) * sizeof(int);
        size = arg1 + p->vsize;
        array = env->NewByteArray(size);
        if (array == NULL) {
            LOGE("effectCallback: Couldn't allocate byte array for parameter data");
            goto effectCallback_Exit;
        }
        bytes = env->GetByteArrayElements(array, NULL);
        memcpy(bytes, p, size);
        env->ReleaseByteArrayElements(array, bytes, 0);
        obj = array;
        LOGV("EVENT_PARAMETER_CHANGED");
       break;
    case AudioEffect::EVENT_ERROR:
        LOGW("EVENT_ERROR");
        break;
    }


// callbackInfo 是由输入参数 user 转化而来： effect_callback_cookie *callbackInfo = (effect_callback_cookie *)user;
// 函数 AudioEffect::enableStatusChanged 调用 effectCallback 时传入的是 mUserData 。
// mUserData 在函数 AudioEffect::set 中被赋值 mUserData = user;
// user 最初由函数 android_media_AudioEffect_native_setup 传给了 AudioEffect 的构造函数，
// 然后传给了函数 AudioEffect::set 。
// user 的最初来源是 lpJniStorage->mCallbackData ， 
// 此处调用的 midPostNativeEvent 函数其实是对象 lpJniStorage->mCallbackData.audioEffect_class = (jclass)env->NewGlobalRef(fields.clazzEffect);
// 的PostNativeEvent函数。
// env->NewGlobalRef(fields.clazzEffect)是创建一个fields.clazzEffect的全局的引用。
// fields.clazzEffect的由来：
//    jclass clazz = env->FindClass(kClassPathName);
// fields.clazzEffect = (jclass)env->NewGlobalRef(clazz);
// kClassPathName 的定义：static const char* const kClassPathName = "android/media/audiofx/AudioEffect";
// fields.midPostNativeEvent 的由来 ：
//    fields.midPostNativeEvent = env->GetStaticMethodID(
//            fields.clazzEffect,
//            "postEventFromNative", "(Ljava/lang/Object;IIILjava/lang/Object;)V");
// 所以，此处调用的其实是 java 侧类 AudioEffect 的 postEventFromNative 函数
    env->CallStaticVoidMethod(
        callbackInfo->audioEffect_class,
        fields.midPostNativeEvent,
        callbackInfo->audioEffect_ref, event, arg1, arg2, obj);
// ++++++++++++++++++++++++++postEventFromNative++++++++++++++++++++++++++++++++++++++
    private static void postEventFromNative(Object effect_ref, int what,
            int arg1, int arg2, Object obj) {
        AudioEffect effect = (AudioEffect) ((WeakReference) effect_ref).get();
// 因为是 weak reference ，存在已被回收的可能
        if (effect == null) {
            return;
        }
// mNativeEventHandler 在函数 createNativeEventHandler 中被赋值
        if (effect.mNativeEventHandler != null) {
// ++++++++++++++++++++++++++++++createNativeEventHandler++++++++++++++++++++++++++++++++++
    // Convenience method for the creation of the native event handler
    // It is called only when a non-null event listener is set.
    // precondition:
    // mNativeEventHandler is null
    private void createNativeEventHandler() {
        Looper looper;
        if ((looper = Looper.myLooper()) != null) {
// 类 NativeEventHandler 中的一个重要函数就是 handleMessage
            mNativeEventHandler = new NativeEventHandler(this, looper);
// +++++++++++++++++++++++++++++handleMessage+++++++++++++++++++++++++++++++++++
        public void handleMessage(Message msg) {
            if (mAudioEffect == null) {
                return;
            }
            switch (msg.what) {
// 通过回调函数，告诉 java 侧状态改变， java 侧作相应相应
            case NATIVE_EVENT_ENABLED_STATUS:
                OnEnableStatusChangeListener enableStatusChangeListener = null;
                synchronized (mListenerLock) {
                    enableStatusChangeListener = mAudioEffect.mEnableStatusChangeListener;
                }
                if (enableStatusChangeListener != null) {
                    enableStatusChangeListener.onEnableStatusChange(
                            mAudioEffect, (boolean) (msg.arg1 != 0));
                }
                break;
            case NATIVE_EVENT_CONTROL_STATUS:
                OnControlStatusChangeListener controlStatusChangeListener = null;
                synchronized (mListenerLock) {
                    controlStatusChangeListener = mAudioEffect.mControlChangeStatusListener;
                }
                if (controlStatusChangeListener != null) {
                    controlStatusChangeListener.onControlStatusChange(
                            mAudioEffect, (boolean) (msg.arg1 != 0));
                }
                break;
            case NATIVE_EVENT_PARAMETER_CHANGED:
                OnParameterChangeListener parameterChangeListener = null;
                synchronized (mListenerLock) {
                    parameterChangeListener = mAudioEffect.mParameterChangeListener;
                }
                if (parameterChangeListener != null) {
                    // arg1 contains offset of parameter value from start of
                    // byte array
                    int vOffset = msg.arg1;
                    byte[] p = (byte[]) msg.obj;
                    // See effect_param_t in EffectApi.h for psize and vsize
                    // fields offsets
                    int status = byteArrayToInt(p, 0);
                    int psize = byteArrayToInt(p, 4);
                    int vsize = byteArrayToInt(p, 8);
                    byte[] param = new byte[psize];
                    byte[] value = new byte[vsize];
                    System.arraycopy(p, 12, param, 0, psize);
                    System.arraycopy(p, vOffset, value, 0, vsize);


                    parameterChangeListener.onParameterChange(mAudioEffect,
                            status, param, value);
                }
                break;


            default:
                Log.e(TAG, "handleMessage() Unknown event type: " + msg.what);
                break;
            }
        }
// -----------------------------handleMessage-----------------------------------
        } else if ((looper = Looper.getMainLooper()) != null) {
            mNativeEventHandler = new NativeEventHandler(this, looper);
        } else {
            mNativeEventHandler = null;
        }
    }

// 函数 setEnableStatusListener 中会调用函数 createNativeEventHandler
// +++++++++++++++++++++++++++++createNativeEventHandler+++++++++++++++++++++++++++++++++++
    /**
     * Sets the listener AudioEffect notifies when the effect engine is enabled
     * or disabled.
     *
     * @param listener
     */
    public void setEnableStatusListener(OnEnableStatusChangeListener listener) {
        synchronized (mListenerLock) {
            mEnableStatusChangeListener = listener;
        }
        if ((listener != null) && (mNativeEventHandler == null)) {
            createNativeEventHandler();
        }
    }
// 应用程序中会创建一个 Listener 并调用函数 setEnableStatusListener 设置到 AudioEffect 对象中。
// 如文件 MediaAudioEffectTest.java 中的 createListenerLooper 函数。
// -----------------------------createNativeEventHandler-----------------------------------
// ------------------------------createNativeEventHandler----------------------------------
            Message m = effect.mNativeEventHandler.obtainMessage(what, arg1,
                    arg2, obj);
            effect.mNativeEventHandler.sendMessage(m);
        }


    }
// --------------------------postEventFromNative--------------------------------------


effectCallback_Exit:
    if (array) {
        env->DeleteLocalRef(array);
    }


    if (env->ExceptionCheck()) {
        env->ExceptionDescribe();
        env->ExceptionClear();
    }
}
// -----------------------------effectCallback-----------------------------------
        }
    }
}
// ----------------------------AudioEffect::enableStatusChanged------------------------------------
        }
// ----------------------------EffectClient::enableStatusChanged------------------------------------
    }
}
// ----------------------------AudioFlinger::EffectHandle::setEnabled------------------------------------
            }
        }
    }
    return NO_ERROR;
}
// -----------------------------AudioFlinger::EffectModule::setEnabled-----------------------------------
}
// -----------------------------AudioFlinger::EffectHandle::enable-----------------------------------
        }
    } else {
        LOGV("disable %p", this);
        if (android_atomic_and(~1, &mEnabled) == 1) {
           return mIEffect->disable();
        }
    }
    return NO_ERROR;
}
// ------------------------------AudioEffect::setEnabled----------------------------------
}
// ------------------------------android_media_AudioEffect_native_setEnabled----------------------------------
    }
// ------------------------------setEnabled----------------------------------
                assertTrue(msg + ": invalid state from getEnabled", effect.getEnabled());
                effect.setEnabled(false);
                assertFalse(msg + ": invalid state to getEnabled", effect.getEnabled());
                result = true;
            } catch (IllegalStateException e) {
                msg = msg.concat(": setEnabled() in wrong state");
            } finally {
                effect.release();
            }
        } catch (IllegalArgumentException e) {
            msg = msg.concat(": Equalizer not found");
            loge(msg, ": Equalizer not found");
        } catch (UnsupportedOperationException e) {
            msg = msg.concat(": Effect library not loaded");
            loge(msg, ": Effect library not loaded");
        }
        assertTrue(msg, result);
    }

###########################################################


&&&&&&&&&&&&&&&&&&&&&&&总结&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
setEnabled 最终会调用到 EffectModule 中的 setEnabled 函数。
函数 EffectModule::setEnabled 会修改当前状态，并调用函数 EffectHandle::setEnabled 。
函数 EffectHandle::setEnabled 会回调到 java 侧的函数 postEventFromNative ，将状态改变告诉给 java 侧。
函数 postEventFromNative 会调用 NativeEventHandler::handleMessage 函数来处理 native 侧过来的 event 。
handleMessage 函数中调用 Listener 的 onEnableStatusChange 函数，将改变告诉给应用成员。
应用程序在初始化阶段会创建一个自己的 Listener ，并将它注册到 AudioEffect 对象。


至于 native 侧如何回调 java 侧的函数， 在后面的文章中再详细介绍。
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&