[pulseaudio-discuss] [PATCH v2 01/10] Add PA_CORE_HOOK_CARD_SET_PROFILE

[Tanu Kaskinen]

On Mon, 2013-12-09 at 20:31 +0200, Tanu Kaskinen wrote:
> diff --git a/src/pulsecore/core.h b/src/pulsecore/core.h
> index 8b4bf05..f8863ae 100644
> --- a/src/pulsecore/core.h
> +++ b/src/pulsecore/core.h
> @@ -115,6 +115,37 @@ typedef enum pa_core_hook {
>      PA_CORE_HOOK_CARD_NEW,
>      PA_CORE_HOOK_CARD_PUT,
>      PA_CORE_HOOK_CARD_UNLINK,
> +
> +    /* Fired when pa_card_set_profile() is called with bypass_router=false.
> +     * Router modules can use this to intercept card profile switch requests.
> +     * Call data: pa_card_set_profile_hook_data.
> +     *
> +     * What does "intercepting profile switch requests" mean? Router modules
> +     * may want to control whether to accept the profile switch, or they may
> +     * want to do something before and after the switch.
> +     *
> +     * The ret_valid field of pa_card_set_profile_hook_data controls an
> +     * important aspect of pa_card_set_profile(): if ret_valid is true after
> +     * the hook returns, it is assumed that a router module took care of the
> +     * profile switch, and pa_card_set_profile() will just return the value of
> +     * the ret field and not continue executing the profile switch.
> +     *
> +     * Denying a profile switch request can be done by setting the ret field
> +     * to an appropriate negative error code and the ret_valid field to true.
> +     *
> +     * Doing something before and after a profile switch can be achieved by
> +     * first doing the "before" thing in the hook callback, then calling
> +     * pa_card_set_profile() with bypass_router=true (so that the hook won't
> +     * be fired again), and then doing the "after" thing. ret_valid must be
> +     * set to true, because the router module already executed the profile
> +     * switch. In this case ret should probably be the return value of the
> +     * "inner" pa_card_set_profile() call.
> +     *
> +     * The hook callback can access the profile and save parameters of the
> +     * pa_card_set_profile() call via the provile and save fields of
> +     * pa_card_set_profile_hook_data. */
> +    PA_CORE_HOOK_CARD_SET_PROFILE,

I have an improved version of this wall of text, here's the diff:

diff --git a/src/pulsecore/core.h b/src/pulsecore/core.h
index f8863ae..78675da 100644
--- a/src/pulsecore/core.h
+++ b/src/pulsecore/core.h
@@ -118,17 +118,24 @@ typedef enum pa_core_hook {
 
     /* Fired when pa_card_set_profile() is called with bypass_router=false.
      * Router modules can use this to intercept card profile switch requests.
-     * Call data: pa_card_set_profile_hook_data.
+     * Call data: pa_card_set_profile_hook_data, details below:
+     *
+     *     struct pa_card_set_profile_hook_data {
+     *         pa_card_profile *profile;
+     *         bool save;
+     *         int ret;
+     *         bool ret_valid;
+     *     }
      *
      * What does "intercepting profile switch requests" mean? Router modules
      * may want to control whether to accept the profile switch, or they may
      * want to do something before and after the switch.
      *
-     * The ret_valid field of pa_card_set_profile_hook_data controls an
-     * important aspect of pa_card_set_profile(): if ret_valid is true after
-     * the hook returns, it is assumed that a router module took care of the
-     * profile switch, and pa_card_set_profile() will just return the value of
-     * the ret field and not continue executing the profile switch.
+     * The ret_valid field of the data struct controls an important aspect of
+     * pa_card_set_profile(): if ret_valid is true after the hook returns, it
+     * is assumed that a router module took care of the profile switch, and
+     * pa_card_set_profile() will just return the value of the ret field and
+     * not continue executing the profile switch.
      *
      * Denying a profile switch request can be done by setting the ret field
      * to an appropriate negative error code and the ret_valid field to true.
@@ -142,8 +149,8 @@ typedef enum pa_core_hook {
      * "inner" pa_card_set_profile() call.
      *
      * The hook callback can access the profile and save parameters of the
-     * pa_card_set_profile() call via the provile and save fields of
-     * pa_card_set_profile_hook_data. */
+     * pa_card_set_profile() call via the profile and save fields of the data
+     * struct. */
     PA_CORE_HOOK_CARD_SET_PROFILE,
 
     PA_CORE_HOOK_CARD_PROFILE_CHANGED,

-- 
Tanu