Visualizza wikitesto di Alsa e Gambas: Client e porte in Invio dati

==Funzione per consentire la relazione del programma Midi con ALSA - Creazione del Client==
Per creare un ''client'' di ALSA <SUP>&#091;[[#Note|Note 1]]&#093;</sup>, è necessario utilizzare la funzione all'uopo dedicata di ALSA: <SUP>&#091;[[#Note|Note 2]]&#093;</sup>
 ''int snd_seq_open (snd_seq_t **seqp, const char *name, int streams, int mode)''
Questa, come abbiamo già detto, fornisce un ''handle'' (la variabile di tipo Puntatore di Puntatore ''seqp'') che consente al programma di relazionarsi con ALSA. Nello specifico ''apre'' il sequencer di ALSA, creando un nuovo ''handle''. Essa apre cioè una connessione all'interfaccia del kernel del sequencer ALSA. Crea dunque un ''client'', e pertanto possiamo dire che ''rende client'' il nostro progetto.

L'impostazione dei parametri di detta funzione è la seguente:
* '''seqp''' : un puntatore <SUP>&#091;[[#Note|Note 3]]&#093;</sup> al puntatore ''snd_seq_t'' (per questo ''**seqp'' è appunto un puntatore ad un puntatore e presenta due asterischi);
* '''name''' : il nome del nostro sequencer. E' un nome stringa che possiede uno speciale significato in ALSA, e solitamente è necessario usare il termine "''default''". Solo successivamente si potrà porre un nome stringa di nostra scelta.
* '''streams''' : la modalità in lettura e/o scrittura del sub-sistema "Sequencer" di ALSA.
Questa modalità può essere:
<p> - SND_SEQ_OPEN_OUTPUT: apre il "Sequencer" solo per l'output (Uscita). Tale modalità è identificata con un valore costante di tipo integer = 1;</p>
<p> - SND_SEQ_OPEN_INPUT: apre il "Sequencer" solo per l'input (Entrata). Tale modalità è identificata con un valore costante di tipo integer = 2;</p>
<p> - SND_SEQ_OPEN_DUPLEX: apre il "Sequencer" sia per l'output che per l'input. Tale modalità è identificata con un valore costante di tipo integer = 3.</p>
*'''mode''' : può assumere il valore di 0, oppure SND_SEQ_NONBLOCK. Esso rappresenta l'apertura del sequencer ALSA in modalità ''non-blocking'', cioè ''non-bloccante'': i dati non bloccheranno in entrata l'esecuzione del programma.


Nella scrittura del nostro codice dobbiamo, come abbiamo imparato, richiamare tale funzione con ''Extern'':
 <Font Color= #B22222>''Private '''EXTERN''' snd_seq_open(seqp AS Pointer, name as String, streams as Integer, mode as Integer) as Integer''</Font>
La chiamata ci restituirà un integer, poiché - come abbiamo già detto - <span style= "text-decoration:underline">ogni funzione esterna di ALSA ritorna un codice di errore</span> (anche quando non si deve necessariamente creare un oggetto/handle). Questa funzione sarà utilizzata nella routine di Gambas così:
 <Font Color= #B22222>''err = snd_seq_open(VarPtr(handle), "default", SND_SEQ_OPEN_OUTPUT, 0)''</font color>
la porta (con riferimento al capitolo che stiamo trattando) ha caratteristica ''OUTPUT''.

Per gestire in Gambas il primo parametro (**seqp) della funzione esterna "''snd_seq_open'' " utilizziamo la funzione:
 ''VarPtr(Variable) AS Pointer''
la quale passa l'indirizzo del puntatore alla variabile "''handle''". Detta funzione di Gambas, cioè, ritorna un puntatore alla variabile "''handle''".


==Attribuire al "Client" un nome==
Potremo poi, volendo, attribuire al "Client" un nome da noi scelto (che avremo scelto già nella chiamata della funzione di apertura di ALSA effettuata nella classe principale). Per fare questo è necessario richiamare una funzione esterna di ALSA - che in C è:
 ''int snd_seq_set_client_name(snd_seq_t *seq, const char *name)''
con il solito Extern:
 <Font Color= #B22222>''Private '''EXTERN''' snd_seq_client_name(seq AS Pointer, name AS String) AS Integer''</Font Color>
Questa funzione sarà utilizzata in Gambas come segue:
 <Font Color= #B22222> ''err = snd_seq_client_name(handle, myname)</font color>


==Ottenere il numero identificativo del Client==
Possiamo inoltre ottenere il valore numerico identificativo del nostro Client. Questo identificativo numerico risulta indispensabile per conoscere od impostare le informazioni sul client. Solitamente ad un client-utente viene attribuito un identificativo tra 128 e 191. Richiamiamo ancora una funzione esterna di ALSA - che in C è:
 ''int snd_seq_client_id(snd_seq_t *seq)''
ovviamente dichiarata in Gambas così:
 <Font Color= #B22222>''Private '''EXTERN''' snd_seq_client_id(seq As Pointer) As Integer''</Font Color>
Questa funzione sarà utilizzata in Gambas come segue:
 <Font Color= #B22222> ''id = snd_seq_client_id(handle)</font color>


==Creazione della Porta e sua ''capacità''==
Dopo aver dato il nome al Client, creiamo effettivamente la sua porta conferendogli la ''capacità''. <SUP>&#091;[[#Note|Note 4]]&#093;</sup>
<BR>Per creare una porta di normale uso si richiamerà la funzione esterna di ALSA - che in C è:
 ''int snd_seq_create_simple_port(snd_seq_t *seq, const char *name, unsigned int caps, unsigned int type)''
in Gambas tale dichiarazione sarà:
 <Font Color= #B22222>''Private '''EXTERN'''  snd_seq_create_simple_port(seq As Pointer, name As String, caps As Integer, type As Integer) As Integer''</Font Color>.</p>

Questa funzione sarà utilizzata in Gambas come segue:
 <Font Color= #B22222>'' err = snd_seq_create_simple_port(handle, "Seq-Out", SND_SEQ_PORT_CAP_READ, SND_SEQ_PORT_TYPE_MIDI_GENERIC + SND_SEQ_PORT_TYPE_APPLICATION)''</font color>

Creiamo la Porta del ''Client'' con ''capacità'' "READ" (ossia di essere ''letta'' da altri ''Client'' di ALSA), nonché con ''capacità'' generica di interpretare i dati Midi, ed in più la dichiariamo appartenente alla nostra applicazione, cioè al nostro sequencer-Client.

Laddove le costanti:
* SND_SEQ_PORT_CAP_READ = 1; <FONT Size=2 Color=gray>''La Porta del sequencer-Client può essere '''letta da un altro Client''' di ALSA ''(''il sequencer-Client può inviare dati alla "sua" Porta'')</font>
* SND_SEQ_PORT_TYPE_MIDI_GENERIC = 2;
* SND_SEQ_PORT_TYPE_APPLICATION = 1048576   (1<<20).


==La ''gestione dell'errore'' in ALSA==
Alle funzioni che ritornano un valore di errore, aggiungeremo la gestione dell'errore.

L'intera funzione per gestire gli errori potrà essere ad esempio così concepita:

1. Come sappiamo, Alsa restituisce codici di errore numerici.

2. Otteniamo quindi il codice di errore, e lo passiamo ad Alsa usando la funzione esterna:
 const char * snd_strerror (int errnum)
che per essere utilizzata ovviamente sarà debitamente richiamata con il solito ''Extern'':
 <Font Color= #B22222>''Private Extern snd_strerror(err As Integer) As Pointer''</font>
Si passerà alla funzione <Font Color= #B22222>''snd_strerror()''</font> il valore Intero ritornato, la quale in base al valore passato ritornerà un messaggio di spiegazione come una stringa che può essere agevolmente letta da Gambas.


==Esempio pratico==
Mostriamo di seguito, a compendio di quanto sopra descritto, un codice di applicazione a ''riga di comando'', nel quale verrà inizializzata la libreria ALSA ed il suo subsistema ''Seq'' e soltanto creata la porta in lettura della nostra applicazione. Con il seguente codice dunque la nostra applicazione diventerà semplicemente così un ''Client'' di ALSA.
 Library "libasound:2.0.0"
 
 Private Const SND_SEQ_OPEN_OUTPUT As Integer = 1
 Private Const SND_SEQ_PORT_CAP_READ As Integer = 1
 Private Const SND_SEQ_PORT_CAP_SUBS_READ As Integer = 32
 Private Const SND_SEQ_PORT_TYPE_MIDI_GENERIC As Integer = 2
 Private Const SND_SEQ_PORT_TYPE_APPLICATION As Integer = 1048576
 
 <FONT Color=gray>' ''int snd_seq_open (snd_seq_t **handle, const char * name, int streams, int mode)''
 ' ''Open the ALSA sequencer.''</font>
 Private Extern snd_seq_open(handle As Pointer, name As String, streams As Integer, mode As Integer) As Integer
 
 <FONT Color=gray>' ''int snd_seq_set_client_name (snd_seq_t *seq, const char *name)''
 ' ''Set client name.''</font>
 Private Extern snd_seq_set_client_name(seq As Pointer, name As String) As Integer
 
 <FONT Color=gray>' ''int snd_seq_client_id (snd_seq_t *handle)''
 ' ''Get the client id.''</font>
 Private Extern snd_seq_client_id(handle As Pointer) As Integer
 
 <FONT Color=gray>' ''int snd_seq_create_simple_port (snd_seq_t *seq, const char *name, unsigned int caps, unsigned int type)''
 ' ''Create a port - simple version.''</font>
 Private Extern snd_seq_create_simple_port(seq As Pointer, name As String, caps As Integer, type As Integer) As Integer
 
 <FONT Color=gray>' ''const char* snd_strerror (int errnum)''
 ' ''Returns the message for an error code.''</font>
 Private Extern snd_strerror(errnum As Integer) As String
 
 <FONT Color=gray>' ''int snd_seq_close (snd_seq_t *handle)
 ' ''Close the sequencer.''</font>
 Private Extern snd_seq_close(handle As Pointer) As Integer
 
 
 Public Sub Main()
 
  Dim handle As Pointer
  Dim rit, id, porta As Integer
  
 <FONT Color=gray>' ''Crea un Client di ALSA:''</font>
  rit = snd_seq_open(VarPtr(handle), "default", SND_SEQ_OPEN_OUTPUT, 0)
  If rit < 0 Then Error.Raise("Impossibile aprire il subsistema 'seq' di ALSA: " & snd_strerror(rit))
    
 <FONT Color=gray>' ''Attribuisce un nome al Client:''</font>
  snd_seq_set_client_name(handle, "Client di ALSA")
    
 <FONT Color=gray>' ''Ottiene il numero identificativo del Client:''</font>
  id = snd_seq_client_id(handle)
  Print "Identificativo del Client: "; id
  
 <FONT Color=gray>' ''Crea una porta del Client; gli assegna la capacità di essere letta (da altri Client) ed effettua la sottoscrizione.''
 ' ''Inoltre ottiene il numero identificativo della porta del Client.''</font>
  porta = snd_seq_create_simple_port(handle, "porta", SND_SEQ_PORT_CAP_READ Or SND_SEQ_PORT_CAP_SUBS_READ, SND_SEQ_PORT_TYPE_MIDI_GENERIC Or SND_SEQ_PORT_TYPE_APPLICATION)
  If porta < 0 Then Error.Raise("Impossibile creare la porta di uscita dati ALSA: " & snd_strerror(rit))
   
  Wait 10
  
  <FONT Color=gray>' ''Chiude il subsistema 'seq' di ALSA e distrugge il Client:''</font>
  snd_seq_close(handle)
  
 End
Alcune informazioni sul nostro applicativo ''Client'' di Alsa sono visibili, fintanto che esso è in funzione, nel file "''/proc/asound/seq/clients''", ove sono elencati appunto i ''Client'' attivi di Alsa.

Va detto che, ovviamente, tutta la parte strettamente afferente alle funzioni esterne di ALSA potrebbe essere raccolta in un Modulo a se stante.



=Note=
[1] Vedere: https://www.alsa-project.org/alsa-doc/alsa-lib/seq.html

[2] Vedi D. Blengino: [[Un_contributo_sulle_funzioni_esterne_in_Gambas_a_cura_di_Doriano_B.#Iniziare_un_dialogo_con_ALSA|Iniziare un dialogo con ALSA]].

[3] I Puntatori (Pointer) sono variabili sulle quali si leggono e si scrivono indirizzi (i pointer contengono indirizzi). Ottenere un valore tramite un Puntatore si dice "''dereferenziare il pointer''", nel senso che il pointer viene interrogato, ed esso dice l'indirizzo di memoria ove cercare i dati.
<BR>Solitamente ai pointer è possibile assegnare il valore NULL, che significa "''non esiste alcun indirizzo''". Se i pointer sono NULL, non devono essere dereferenziati, pena (di solito) un errore del sistema operativo.

[4] Si è spiegato nella seguente pagina "[[ALSA_e_Gambas_-_Subsistema_Seq:_Il_Client_di_Alsa_e_le_sue_porte|Il Client di Alsa e le sue Porte]]" il concetto di "''Capacità'' " della Porta del ''Client'' di ALSA ed il loro funzionamento.
<BR>In particolare si è detto che la definizione della "''Capacità'' " ("READ", "WRITE" o "DUPLEX") della Porta deve essere considerata sempre <SPAN Style="text-decoration:underline">dal punto di vista dell'altro Client</span> di ALSA al quale ci si vuole connettere via ALSA.
<BR>Così dunque la Porta del ''Client'' dichiarata con ''Capacità'' "READ", vuol dire che gli altri ''Client'' di ALSA possono "leggere" i dati provenienti dal ''Client'' proprietario della Porta in questione.

Con il passaggio della Costante al terzo parametro della funzione "snd_seq_open()" si imposta la modalità di gestione del flusso di dati da parte del sub-sistema "Sequencer" di ALSA.
<BR>Così l'attribuzione a quel parametro formale, ad esempio, della Costante "''SND_SEQ_OPEN_OUTPUT'' " sta a significare che il ''Sequencer'' di ALSA è capace di gestire il flusso di dati in Uscita. In tal caso ne consegue che la Porta del ''Client'', utile per connettersi agli altri ''Client'' di ALSA, dovrà avere necessariamente una ''Capacità'' "READ.
<BR>Sempre restando all'esempio fatto, il ''Client'' creato può ''scrivere'' in uscita (OUTPUT) sulla "sua" Porta che ha la ''Capacità'' di farsi "leggere" dagli altri eventuali ''Client'', ai quali lo stesso si è connesso.

Quindi in base a quale Costante sia stata passata al terzo argomento della funzione "snd_seq_open()", si dovrà impostare con apposite Costanti fornite da ALSA necessariamente una specifica "''Capacità'' " della Porta del ''Client'', come segue:
<TABLE>
  <TR align=center>
    <TD><B>Stream Client</b></td><TD></td><TD><B>Capacità Porta</b></td><TD></td>
  </tr>
  <TR>
  <TD>SND_SEQ_OPEN_OUTPUT</td><TD> ←→ </td><TD align=center>READ</td><TD> (SND_SEQ_PORT_CAP_READ)</td>
  </tr>
  <TR>
  <TD>SND_SEQ_OPEN_INPUT</td><TD> ←→ </td><TD align=center>WRITE</td><TD> (SND_SEQ_PORT_CAP_WRITE)</td>
  </tr>
  <TR>
  <TD>SND_SEQ_OPEN_DUPLEX</td><TD> ←→ </td><TD align=center>DUPLEX</td><TD> (SND_SEQ_PORT_CAP_DUPLEX)</td>
  </tr>
</table>