Alsa-Hook-Plugin

Object: Provide a Hook on Alsa PCM to check permission again AGL Advance Audio Agent
Status: Release Candidate
Author: Fulup Ar Foll fulup@iot.bzh
Date  : August-2017

Functionalities:
 - Execute a set of unix/ws RPC request again AGL binders to allow/deny access
 - Keep websocket open in an idependant thread in order to monitor event received from AGL audio agent

Installation
 - Alsaplugins are typically search in /usr/share/alsa-lib. Nevertheless a full path might be given
 - This plugin implement a hook on a slave PCM. Typically this slave PCM is a dedicated virtual channel (eg: navigation, emergency,...)
 - Config should be place in ~/.asoundrc (see config sample in PROJECT_ROOT/conf.d/alsa)

Test
 - Install a full .asoundrc from conf.d/project/alsa.d
 - speaker-test -DMyNavigationHook -c2 -twav

Config
```
# 
# Author: Fulup Ar Foll
# Object: PCM hook type 
#
# Test  :  Note: Jabra_USB=hw:v1340
#  Check SoundCard ==> speaker-test -Dhw:v1340   -c2 -twav
#  Check MixerPCM  ==> speaker-test -DSpeakers   -c2 -twav 
#  Check SoftVol   ==> speaker-test -DMusicPCM   -c2 -twav 
#  Check Plugin    ==> speaker-test -DMultimedia -c2 -twav
#  MultiMedia aplay -DDMyNavPCM /usr/share/sounds/alsa/test.wav
#
# Bug/Feature: when softvol control is initialised from plugin and not
#    from AGL binding. At 1st run ctl has invalid TLV and cannot be
#    use. Bypass Solution: 
#     * start audio-binder before playing sound (binding create control before softvol plugin)
#     * run a dummy aplay -DMyNavPCM "" to get a clean control
#
# References: https://www.spinics.net/lists/alsa-devel/msg54235.html
# --------------------------------------------------------------------

# ------------------------------------------------------
# Mixer PCM allow to play multiple stream simultaneously
# ------------------------------------------------------
pcm.Speakers { 
    type dmix            
    slave {pcm "hw:v1340"}  #Jabra Solmate 1
    ipc_key 1001          # ipc_key should be unique to each dmix
} 

# -----------------------------------------------------
#  Register ControllerHookPlugin (ToiBeFix fullpath)
# -----------------------------------------------------
pcm_hook_type.CtlHookPlugin {
    install "AlsaInstallHook" 
    lib "/home/fulup/Workspace/Audio-4a/alsa-4a/build/hook-plugin/policy_hook_tcp.so"
    #lib "/home/fulup/Workspace/Audio-4a/alsa-4a/build/hook-plugin/policy_hook_unix.so"
}


# -------------------------------------------------------
# Define one Audio Virtual Channel per Audio Roles
# -------------------------------------------------------
pcm.MusicPCM {
    type softvol

    # Point Slave on HOOK for policies control
    slave.pcm "Speakers"

    # name should match with HAL definition
    control.name  "Playback Multimedia"
}

# ----------------------------------------------------
# Define one hooked PCM channel per Audio Roles
# ----------------------------------------------------
pcm.Multimedia {
    type hooks
    slave {pcm "MusicPCM"}
    hooks.0 {
        comment "Defined used hook sharelib and provide arguments/config to install func"
        type "CtlHookPlugin"
        hook_args {

            # print few log messages (default false)
            verbose true 

            # uri to audio-4a policy engine
            uri="ws://localhost:1234/api?token='audio-agent-token'"
            #ws-client="unix:/var/tmp/pol4a"

            # api subcall to request a role
            controls {
                # Request authorisation to write on navigation
                navigation-ctl {
                    request "multimedia-role"
                    release "release-role"
                    args    "{'uid':'alsa-hook-navigation'}"
                }
            }
            events {    # map event reception to self generated signal
                pause  30
                resume 31
                stop   3
            }
        }
    }
}


```

NOTE:

* Hook plugin is loaded by Alsa libasound within client context. It inherits client process attributes, as UID/GID and
SMACK label when running on AGL. The smack label is control by AGL security framework.
As a result a control request succeeds only when client application permission match requested audio role inside Cynara security database.

* Hook plugin keep a connection with the Audio-Agent until PCM is closed by the application. This connection allow the
Audio-Agent to send events. eg: pause, quit, mute, ...