LIBFFADO 2.999.0

ffado.h

Go to the documentation of this file.
00001 /* ffado.h
00002  *
00003  * Copyright (C) 2005-2008 by Pieter Palmers
00004  * Copyright (C) 2005-2008 by Daniel Wagner
00005  *
00006  * This file is part of FFADO
00007  * FFADO = Free Firewire (pro-)audio drivers for linux
00008  *
00009  * FFADO is based upon FreeBoB
00010  *
00011  * This program is free software: you can redistribute it and/or modify
00012  * it under the terms of the GNU General Public License as published by
00013  * the Free Software Foundation, either version 2 of the License, or
00014  * (at your option) version 3 of the License.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
00023  *
00024  */
00025 
00026 #ifndef FFADO_H
00027 #define FFADO_H
00028 
00029 #define FFADO_MAX_NAME_LEN 256
00030 
00031 #include <stdlib.h>
00032 
00033 #define FFADO_STREAMING_MAX_URL_LENGTH 2048
00034 
00035 #define FFADO_IGNORE_CAPTURE         (1<<0)
00036 #define FFADO_IGNORE_PLAYBACK     (1<<1)
00037 
00038 enum ffado_direction {
00039     FFADO_CAPTURE  = 0,
00040     FFADO_PLAYBACK = 1,
00041 };
00042 
00043 typedef struct ffado_handle* ffado_handle_t;
00044 
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #endif
00048 
00049 /* ABI stuff */
00050 const char*
00051 ffado_get_version();
00052 
00053 int
00054 ffado_get_api_version();
00055 
00056 /* various function */
00057 
00058 /* The basic operation of the API is as follows:
00059  * 
00060  * ffado_streaming_init()
00061  * ffado_streaming_start()
00062  * while(running) {
00063  *   retval = ffado_streaming_wait();
00064  *   if (retval == -1) {
00065  *     ffado_streaming_reset();
00066  *     continue;
00067  *   }
00068  *
00069  *   ffado_streaming_transfer_buffers(dev);
00070  *
00071  *   for(all channels) {
00072  *     switch (channel_type) {
00073  *     case audio:
00074  *       bytesread=ffado_streaming_read(audioinbuffer[channel]);
00075  *       byteswritten=ffado_streaming_write(audiooutbuffer[channel]);
00076  *     case midi:
00077  *       bytesread=ffado_streaming_read(midiinbuffer[channel]);
00078  *       byteswritten=ffado_streaming_write(midioutbuffer[channel]);
00079  *     }
00080  *   }
00081  * }
00082  * ffado_streaming_stop();
00083  * ffado_streaming_finish();
00084  *
00085  */
00086 
00087 typedef struct _ffado_device ffado_device_t;
00088 
00093 typedef unsigned int ffado_sample_t; // FIXME
00094 typedef unsigned int ffado_nframes_t;
00095 
00096 #define FFADO_MAX_SPECSTRING_LENGTH 256
00097 #define FFADO_MAX_SPECSTRINGS       64
00098 
00135 typedef struct ffado_device_info {
00136     unsigned int nb_device_spec_strings;
00137     char **device_spec_strings;
00138 
00139     /* add some extra space to allow for future API extention 
00140        w/o breaking binary compatibility */
00141     int32_t reserved[32];
00142 } ffado_device_info_t;
00143 
00147 typedef struct ffado_options {
00148     /* driver related setup */
00149     int32_t sample_rate;         /*
00150                              * you can specify a value here or -1 to autodetect
00151                               */
00152 
00153     /* buffer setup */
00154     int32_t period_size;     /* one period is the amount of frames that
00155                  * has to be sent or received in order for
00156                  * a period boundary to be signalled.
00157                  * (unit: frames)
00158                  */
00159     int32_t nb_buffers;    /* the size of the frame buffer (in periods) */
00160 
00161     /* packetizer thread options */
00162     int32_t realtime;
00163     int32_t packetizer_priority;
00164 
00165     /* verbosity */
00166     int32_t verbose;
00167 
00168     /* slave mode */
00169     int32_t slave_mode;
00170     /* snoop mode */
00171     int32_t snoop_mode;
00172 
00173     /* add some extra space to allow for future API extention 
00174        w/o breaking binary compatibility */
00175     int32_t reserved[24];
00176 
00177 } ffado_options_t;
00178 
00194 typedef enum {
00195       ffado_stream_type_invalid                      =   -1,
00196       ffado_stream_type_unknown                      =   0,
00197       ffado_stream_type_audio                        =   1,
00198       ffado_stream_type_midi                         =   2,
00199       ffado_stream_type_control                      =   3,
00200 } ffado_streaming_stream_type;
00201 
00207 typedef enum {
00208     ffado_audio_datatype_error           = -1,
00209     ffado_audio_datatype_int24           =  0,
00210     ffado_audio_datatype_float           =  1,
00211 } ffado_streaming_audio_datatype;
00212 
00218 typedef enum {
00219     ffado_wait_shutdown        = -3,
00220     ffado_wait_error           = -2,
00221     ffado_wait_xrun            = -1,
00222     ffado_wait_ok              =  0,
00223 } ffado_wait_response;
00224 
00240 ffado_device_t *ffado_streaming_init(
00241                      ffado_device_info_t device_info,
00242                      ffado_options_t options);
00243 
00251 int ffado_streaming_prepare(ffado_device_t *dev);
00252 
00253 
00260 void ffado_streaming_finish(ffado_device_t *dev);
00261 
00270 int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev);
00271 
00280 int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev);
00281 
00292 int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
00293 
00304 int ffado_streaming_get_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
00305 
00314 ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number);
00315 
00324 ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number);
00325 /*
00326  *
00327  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
00328  * and separately indicate if you want to use a user buffer or a managed buffer.
00329  *
00330  */
00331 
00346 int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff);
00347 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
00348 
00361 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
00362 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
00363 
00364 ffado_streaming_audio_datatype ffado_streaming_get_audio_datatype(ffado_device_t *dev);
00365 int ffado_streaming_set_audio_datatype(ffado_device_t *dev, ffado_streaming_audio_datatype t);
00366 
00375 int ffado_streaming_prepare(ffado_device_t *dev);
00376 
00385 int ffado_streaming_start(ffado_device_t *dev);
00386 
00395 int ffado_streaming_stop(ffado_device_t *dev);
00396 
00407 int ffado_streaming_reset(ffado_device_t *dev);
00408 
00417 ffado_wait_response ffado_streaming_wait(ffado_device_t *dev);
00418 
00445 int ffado_streaming_transfer_buffers(ffado_device_t *dev);
00446 
00464 int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev);
00465 
00483 int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev);
00484 
00485 #ifdef __cplusplus
00486 }
00487 #endif
00488 
00489 #endif /* FFADO_STREAMING */