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_capture_buffers(dev);
00070  *
00071  *   for(all channels) {
00072  *     // For both audio and MIDI channels, captured data is available
00073  *     // in the buffer previously set with a call to
00074  *     //   ffado_streaming_set_capture_stream_buffer(dev, channel, buffer)
00075  *     switch (channel_type) {
00076  *     case audio:
00077  *       // Process incoming audio as needed
00078  *     case midi:
00079  *       // Process incoming MIDI data as needed
00080  *     }
00081  *   }
00082  *
00083  *   for(all channels) {
00084  *     // For both audio and MIDI channels, data is written to buffers
00085  *     // previously associated with the playback channel streams using
00086  *     //   ffado_streaming_set_playback_stream_buffer(dev, channel, buffer)
00087  *     switch (channel_type) {
00088  *     case audio:
00089  *       // Set audio playback buffer contents
00090  *     case midi:
00091  *       // Set MIDI playback buffer contents
00092  *     }
00093  *   }
00094  *   ffado_streaming_transfer_playback_buffers(dev);
00095  *
00096  * }
00097  * ffado_streaming_stop();
00098  * ffado_streaming_finish();
00099  *
00100  */
00101 
00102 typedef struct _ffado_device ffado_device_t;
00103 
00108 typedef unsigned int ffado_sample_t; // FIXME
00109 typedef unsigned int ffado_nframes_t;
00110 
00111 #define FFADO_MAX_SPECSTRING_LENGTH 256
00112 #define FFADO_MAX_SPECSTRINGS       64
00113 
00150 typedef struct ffado_device_info {
00151     unsigned int nb_device_spec_strings;
00152     char **device_spec_strings;
00153 
00154     /* add some extra space to allow for future API extention 
00155        w/o breaking binary compatibility */
00156     int32_t reserved[32];
00157 } ffado_device_info_t;
00158 
00162 typedef struct ffado_options {
00163     /* driver related setup */
00164     int32_t sample_rate;         /*
00165                              * you can specify a value here or -1 to autodetect
00166                               */
00167 
00168     /* buffer setup */
00169     int32_t period_size;     /* one period is the amount of frames that
00170                  * has to be sent or received in order for
00171                  * a period boundary to be signalled.
00172                  * (unit: frames)
00173                  */
00174     int32_t nb_buffers;    /* the size of the frame buffer (in periods) */
00175 
00176     /* packetizer thread options */
00177     int32_t realtime;
00178     int32_t packetizer_priority;
00179 
00180     /* verbosity */
00181     int32_t verbose;
00182 
00183     /* slave mode */
00184     int32_t slave_mode;
00185     /* snoop mode */
00186     int32_t snoop_mode;
00187 
00188     /* add some extra space to allow for future API extention 
00189        w/o breaking binary compatibility */
00190     int32_t reserved[24];
00191 
00192 } ffado_options_t;
00193 
00209 typedef enum {
00210       ffado_stream_type_invalid                      =   -1,
00211       ffado_stream_type_unknown                      =   0,
00212       ffado_stream_type_audio                        =   1,
00213       ffado_stream_type_midi                         =   2,
00214       ffado_stream_type_control                      =   3,
00215 } ffado_streaming_stream_type;
00216 
00222 typedef enum {
00223     ffado_audio_datatype_error           = -1,
00224     ffado_audio_datatype_int24           =  0,
00225     ffado_audio_datatype_float           =  1,
00226 } ffado_streaming_audio_datatype;
00227 
00233 typedef enum {
00234     ffado_wait_shutdown        = -3,
00235     ffado_wait_error           = -2,
00236     ffado_wait_xrun            = -1,
00237     ffado_wait_ok              =  0,
00238 } ffado_wait_response;
00239 
00255 ffado_device_t *ffado_streaming_init(
00256                      ffado_device_info_t device_info,
00257                      ffado_options_t options);
00258 
00266 int ffado_streaming_prepare(ffado_device_t *dev);
00267 
00268 
00275 void ffado_streaming_finish(ffado_device_t *dev);
00276 
00285 int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev);
00286 
00295 int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev);
00296 
00307 int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
00308 
00319 int ffado_streaming_get_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
00320 
00329 ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number);
00330 
00339 ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number);
00340 /*
00341  *
00342  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
00343  * and separately indicate if you want to use a user buffer or a managed buffer.
00344  *
00345  */
00346 
00361 int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff);
00362 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
00363 
00376 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
00377 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
00378 
00379 ffado_streaming_audio_datatype ffado_streaming_get_audio_datatype(ffado_device_t *dev);
00380 int ffado_streaming_set_audio_datatype(ffado_device_t *dev, ffado_streaming_audio_datatype t);
00381 
00390 int ffado_streaming_prepare(ffado_device_t *dev);
00391 
00400 int ffado_streaming_start(ffado_device_t *dev);
00401 
00410 int ffado_streaming_stop(ffado_device_t *dev);
00411 
00422 int ffado_streaming_reset(ffado_device_t *dev);
00423 
00432 ffado_wait_response ffado_streaming_wait(ffado_device_t *dev);
00433 
00460 int ffado_streaming_transfer_buffers(ffado_device_t *dev);
00461 
00479 int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev);
00480 
00498 int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev);
00499 
00500 #ifdef __cplusplus
00501 }
00502 #endif
00503 
00504 #endif /* FFADO_STREAMING */