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
