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_API_VERSION 9
00030 
00031 #define FFADO_MAX_NAME_LEN 256
00032 
00033 #include <stdlib.h>
00034 
00035 #define FFADO_STREAMING_MAX_URL_LENGTH 2048
00036 
00037 #define FFADO_IGNORE_CAPTURE         (1<<0)
00038 #define FFADO_IGNORE_PLAYBACK     (1<<1)
00039 
00040 enum ffado_direction {
00041     FFADO_CAPTURE  = 0,
00042     FFADO_PLAYBACK = 1,
00043 };
00044 
00045 typedef struct ffado_handle* ffado_handle_t;
00046 
00047 #ifdef __cplusplus
00048 extern "C" {
00049 #endif
00050 
00051 #ifdef __APPLE__
00052 #define WEAK_ATTRIBUTE weak_import
00053 #else
00054 #define WEAK_ATTRIBUTE __weak__
00055 #endif
00056 
00057 #ifdef __GNUC__
00058 #define FFADO_WEAK_EXPORT __attribute__((WEAK_ATTRIBUTE))
00059 #else
00060 /* Add support for non-gcc platforms here */
00061 #endif
00062 
00063 /* ABI stuff */
00064 const char*
00065 ffado_get_version();
00066 
00067 int
00068 ffado_get_api_version();
00069 
00070 /* various function */
00071 
00072 /* The basic operation of the API is as follows:
00073  * 
00074  * ffado_streaming_init()
00075  * ffado_streaming_start()
00076  * while(running) {
00077  *   retval = ffado_streaming_wait();
00078  *   if (retval == -1) {
00079  *     ffado_streaming_reset();
00080  *     continue;
00081  *   }
00082  *
00083  *   ffado_streaming_transfer_capture_buffers(dev);
00084  *
00085  *   for(all channels) {
00086  *     // For both audio and MIDI channels, captured data is available
00087  *     // in the buffer previously set with a call to
00088  *     //   ffado_streaming_set_capture_stream_buffer(dev, channel, buffer)
00089  *     switch (channel_type) {
00090  *     case audio:
00091  *       // Process incoming audio as needed
00092  *     case midi:
00093  *       // Process incoming MIDI data as needed
00094  *     }
00095  *   }
00096  *
00097  *   for(all channels) {
00098  *     // For both audio and MIDI channels, data is written to buffers
00099  *     // previously associated with the playback channel streams using
00100  *     //   ffado_streaming_set_playback_stream_buffer(dev, channel, buffer)
00101  *     switch (channel_type) {
00102  *     case audio:
00103  *       // Set audio playback buffer contents
00104  *     case midi:
00105  *       // Set MIDI playback buffer contents
00106  *     }
00107  *   }
00108  *   ffado_streaming_transfer_playback_buffers(dev);
00109  *
00110  * }
00111  * ffado_streaming_stop();
00112  * ffado_streaming_finish();
00113  *
00114  */
00115 
00116 typedef struct _ffado_device ffado_device_t;
00117 
00122 typedef unsigned int ffado_sample_t; // FIXME
00123 typedef unsigned int ffado_nframes_t;
00124 
00125 #define FFADO_MAX_SPECSTRING_LENGTH 256
00126 #define FFADO_MAX_SPECSTRINGS       64
00127 
00164 typedef struct ffado_device_info {
00165     unsigned int nb_device_spec_strings;
00166     char **device_spec_strings;
00167 
00168     /* add some extra space to allow for future API extention 
00169        w/o breaking binary compatibility */
00170     int32_t reserved[32];
00171 } ffado_device_info_t;
00172 
00176 typedef struct ffado_options {
00177     /* driver related setup */
00178     int32_t sample_rate;         /*
00179                              * you can specify a value here or -1 to autodetect
00180                               */
00181 
00182     /* buffer setup */
00183     int32_t period_size;     /* one period is the amount of frames that
00184                  * has to be sent or received in order for
00185                  * a period boundary to be signalled.
00186                  * (unit: frames)
00187                  */
00188     int32_t nb_buffers;    /* the size of the frame buffer (in periods) */
00189 
00190     /* packetizer thread options */
00191     int32_t realtime;
00192     int32_t packetizer_priority;
00193 
00194     /* verbosity */
00195     int32_t verbose;
00196 
00197     /* slave mode */
00198     int32_t slave_mode;
00199     /* snoop mode */
00200     int32_t snoop_mode;
00201 
00202     /* add some extra space to allow for future API extention 
00203        w/o breaking binary compatibility */
00204     int32_t reserved[24];
00205 
00206 } ffado_options_t;
00207 
00223 typedef enum {
00224       ffado_stream_type_invalid                      =   -1,
00225       ffado_stream_type_unknown                      =   0,
00226       ffado_stream_type_audio                        =   1,
00227       ffado_stream_type_midi                         =   2,
00228       ffado_stream_type_control                      =   3,
00229 } ffado_streaming_stream_type;
00230 
00236 typedef enum {
00237     ffado_audio_datatype_error           = -1,
00238     ffado_audio_datatype_int24           =  0,
00239     ffado_audio_datatype_float           =  1,
00240 } ffado_streaming_audio_datatype;
00241 
00247 typedef enum {
00248     ffado_wait_shutdown        = -3,
00249     ffado_wait_error           = -2,
00250     ffado_wait_xrun            = -1,
00251     ffado_wait_ok              =  0,
00252 } ffado_wait_response;
00253 
00269 ffado_device_t *ffado_streaming_init(
00270                      ffado_device_info_t device_info,
00271                      ffado_options_t options);
00272 
00282 int ffado_streaming_set_period_size(ffado_device_t *dev, 
00283                      unsigned int period) FFADO_WEAK_EXPORT;
00284 
00292 int ffado_streaming_prepare(ffado_device_t *dev);
00293 
00294 
00301 void ffado_streaming_finish(ffado_device_t *dev);
00302 
00311 int ffado_streaming_get_nb_capture_streams(ffado_device_t *dev);
00312 
00321 int ffado_streaming_get_nb_playback_streams(ffado_device_t *dev);
00322 
00333 int ffado_streaming_get_capture_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
00334 
00345 int ffado_streaming_get_playback_stream_name(ffado_device_t *dev, int number, char* buffer, size_t buffersize);
00346 
00355 ffado_streaming_stream_type ffado_streaming_get_capture_stream_type(ffado_device_t *dev, int number);
00356 
00365 ffado_streaming_stream_type ffado_streaming_get_playback_stream_type(ffado_device_t *dev, int number);
00366 /*
00367  *
00368  * Note: buffer handling will change in order to allow setting the sample type for *_read and *_write
00369  * and separately indicate if you want to use a user buffer or a managed buffer.
00370  *
00371  */
00372 
00387 int ffado_streaming_set_capture_stream_buffer(ffado_device_t *dev, int number, char *buff);
00388 int ffado_streaming_capture_stream_onoff(ffado_device_t *dev, int number, int on);
00389 
00402 int ffado_streaming_set_playback_stream_buffer(ffado_device_t *dev, int number, char *buff);
00403 int ffado_streaming_playback_stream_onoff(ffado_device_t *dev, int number, int on);
00404 
00405 ffado_streaming_audio_datatype ffado_streaming_get_audio_datatype(ffado_device_t *dev);
00406 int ffado_streaming_set_audio_datatype(ffado_device_t *dev, ffado_streaming_audio_datatype t);
00407 
00416 int ffado_streaming_prepare(ffado_device_t *dev);
00417 
00426 int ffado_streaming_start(ffado_device_t *dev);
00427 
00436 int ffado_streaming_stop(ffado_device_t *dev);
00437 
00448 int ffado_streaming_reset(ffado_device_t *dev);
00449 
00458 ffado_wait_response ffado_streaming_wait(ffado_device_t *dev);
00459 
00486 int ffado_streaming_transfer_buffers(ffado_device_t *dev);
00487 
00505 int ffado_streaming_transfer_playback_buffers(ffado_device_t *dev);
00506 
00524 int ffado_streaming_transfer_capture_buffers(ffado_device_t *dev);
00525 
00526 #ifdef __cplusplus
00527 }
00528 #endif
00529 
00530 #endif /* FFADO_STREAMING */

Generated for LIBFFADO by doxygen 1.8.0