4
* $Id: pa_stream.h 1339 2008-02-15 07:50:33Z rossb $
5
* Portable Audio I/O Library
8
* Based on the Open Source API proposed by Ross Bencina
9
* Copyright (c) 1999-2008 Ross Bencina, Phil Burk
11
* Permission is hereby granted, free of charge, to any person obtaining
12
* a copy of this software and associated documentation files
13
* (the "Software"), to deal in the Software without restriction,
14
* including without limitation the rights to use, copy, modify, merge,
15
* publish, distribute, sublicense, and/or sell copies of the Software,
16
* and to permit persons to whom the Software is furnished to do so,
17
* subject to the following conditions:
19
* The above copyright notice and this permission notice shall be
20
* included in all copies or substantial portions of the Software.
22
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
23
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
25
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
26
* ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
27
* CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
28
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
32
* The text above constitutes the entire PortAudio license; however,
33
* the PortAudio community also makes the following non-binding requests:
35
* Any person wishing to distribute modifications to the Software is
36
* requested to send the modifications to the original developer so that
37
* they can be incorporated into the canonical version. It is also
38
* requested that these non-binding requests be included along with the
45
@brief Stream interfaces, representation structures and helper functions
46
used to interface between pa_front.c host API implementations.
50
#include "portaudio.h"
55
#endif /* __cplusplus */
58
#define PA_STREAM_MAGIC (0x18273645)
61
/** A structure representing an (abstract) interface to a host API. Contains
62
pointers to functions which implement the interface.
64
All PaStreamInterface functions are guaranteed to be called with a non-null,
65
valid stream parameter.
68
PaError (*Close)( PaStream* stream );
69
PaError (*Start)( PaStream *stream );
70
PaError (*Stop)( PaStream *stream );
71
PaError (*Abort)( PaStream *stream );
72
PaError (*IsStopped)( PaStream *stream );
73
PaError (*IsActive)( PaStream *stream );
74
PaTime (*GetTime)( PaStream *stream );
75
double (*GetCpuLoad)( PaStream* stream );
76
PaError (*Read)( PaStream* stream, void *buffer, unsigned long frames );
77
PaError (*Write)( PaStream* stream, const void *buffer, unsigned long frames );
78
signed long (*GetReadAvailable)( PaStream* stream );
79
signed long (*GetWriteAvailable)( PaStream* stream );
80
} PaUtilStreamInterface;
83
/** Initialize the fields of a PaUtilStreamInterface structure.
85
void PaUtil_InitializeStreamInterface( PaUtilStreamInterface *streamInterface,
86
PaError (*Close)( PaStream* ),
87
PaError (*Start)( PaStream* ),
88
PaError (*Stop)( PaStream* ),
89
PaError (*Abort)( PaStream* ),
90
PaError (*IsStopped)( PaStream* ),
91
PaError (*IsActive)( PaStream* ),
92
PaTime (*GetTime)( PaStream* ),
93
double (*GetCpuLoad)( PaStream* ),
94
PaError (*Read)( PaStream* stream, void *buffer, unsigned long frames ),
95
PaError (*Write)( PaStream* stream, const void *buffer, unsigned long frames ),
96
signed long (*GetReadAvailable)( PaStream* stream ),
97
signed long (*GetWriteAvailable)( PaStream* stream ) );
100
/** Dummy Read function for use in interfaces to a callback based streams.
101
Pass to the Read parameter of PaUtil_InitializeStreamInterface.
102
@return An error code indicating that the function has no effect
103
because the stream is a callback stream.
105
PaError PaUtil_DummyRead( PaStream* stream,
107
unsigned long frames );
110
/** Dummy Write function for use in an interfaces to callback based streams.
111
Pass to the Write parameter of PaUtil_InitializeStreamInterface.
112
@return An error code indicating that the function has no effect
113
because the stream is a callback stream.
115
PaError PaUtil_DummyWrite( PaStream* stream,
117
unsigned long frames );
120
/** Dummy GetReadAvailable function for use in interfaces to callback based
121
streams. Pass to the GetReadAvailable parameter of PaUtil_InitializeStreamInterface.
122
@return An error code indicating that the function has no effect
123
because the stream is a callback stream.
125
signed long PaUtil_DummyGetReadAvailable( PaStream* stream );
128
/** Dummy GetWriteAvailable function for use in interfaces to callback based
129
streams. Pass to the GetWriteAvailable parameter of PaUtil_InitializeStreamInterface.
130
@return An error code indicating that the function has no effect
131
because the stream is a callback stream.
133
signed long PaUtil_DummyGetWriteAvailable( PaStream* stream );
137
/** Dummy GetCpuLoad function for use in an interface to a read/write stream.
138
Pass to the GetCpuLoad parameter of PaUtil_InitializeStreamInterface.
141
double PaUtil_DummyGetCpuLoad( PaStream* stream );
144
/** Non host specific data for a stream. This data is used by pa_front to
145
forward to the appropriate functions in the streamInterface structure.
147
typedef struct PaUtilStreamRepresentation {
148
unsigned long magic; /**< set to PA_STREAM_MAGIC */
149
struct PaUtilStreamRepresentation *nextOpenStream; /**< field used by multi-api code */
150
PaUtilStreamInterface *streamInterface;
151
PaStreamCallback *streamCallback;
152
PaStreamFinishedCallback *streamFinishedCallback;
154
PaStreamInfo streamInfo;
155
} PaUtilStreamRepresentation;
158
/** Initialize a PaUtilStreamRepresentation structure.
160
@see PaUtil_InitializeStreamRepresentation
162
void PaUtil_InitializeStreamRepresentation(
163
PaUtilStreamRepresentation *streamRepresentation,
164
PaUtilStreamInterface *streamInterface,
165
PaStreamCallback *streamCallback,
169
/** Clean up a PaUtilStreamRepresentation structure previously initialized
170
by a call to PaUtil_InitializeStreamRepresentation.
172
@see PaUtil_InitializeStreamRepresentation
174
void PaUtil_TerminateStreamRepresentation( PaUtilStreamRepresentation *streamRepresentation );
177
/** Check that the stream pointer is valid.
179
@return Returns paNoError if the stream pointer appears to be OK, otherwise
180
returns an error indicating the cause of failure.
182
PaError PaUtil_ValidateStreamPointer( PaStream *stream );
185
/** Cast an opaque stream pointer into a pointer to a PaUtilStreamRepresentation.
187
@see PaUtilStreamRepresentation
189
#define PA_STREAM_REP( stream )\
190
((PaUtilStreamRepresentation*) (stream) )
193
/** Cast an opaque stream pointer into a pointer to a PaUtilStreamInterface.
195
@see PaUtilStreamRepresentation, PaUtilStreamInterface
197
#define PA_STREAM_INTERFACE( stream )\
198
PA_STREAM_REP( (stream) )->streamInterface
204
#endif /* __cplusplus */
205
#endif /* PA_STREAM_H */