Commit c59d42b6 authored by Timothy B. Terriberry's avatar Timothy B. Terriberry

Improve source/stream terminology consistency

We inherited the term "source" from vorbisfile's "datasource", but
 were using it interchangeably with stream.
At least one user did not even realize the that the _source
 parameter passed to op_open_callbacks() was the same as the
 _stream parameter taken by those callbacks, which is reasonable
 because we never said so.
Consistently use "stream" instead of "source" in both the
 documentation and the code.
parent 881a54da
......@@ -1155,16 +1155,18 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
int *_error,...) OP_ARG_NONNULL(1);
/**Open a stream using the given set of callbacks to access it.
\param _source The stream to read from (e.g., a <code>FILE *</code>).
\param _stream The stream to read from (e.g., a <code>FILE *</code>).
This value will be passed verbatim as the first
argument to all of the callbacks.
\param _cb The callbacks with which to access the stream.
<code><a href="#op_read_func">read()</a></code> must
be implemented.
<code><a href="#op_seek_func">seek()</a></code> and
<code><a href="#op_tell_func">tell()</a></code> may
be <code>NULL</code>, or may always return -1 to
indicate a source is unseekable, but if
indicate a stream is unseekable, but if
<code><a href="#op_seek_func">seek()</a></code> is
implemented and succeeds on a particular source, then
implemented and succeeds on a particular stream, then
<code><a href="#op_tell_func">tell()</a></code> must
also.
<code><a href="#op_close_func">close()</a></code> may
......@@ -1227,11 +1229,11 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
basic validity checks.</dd>
</dl>
\return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.
<tt>libopusfile</tt> does <em>not</em> take ownership of the source
<tt>libopusfile</tt> does <em>not</em> take ownership of the stream
if the call fails.
The calling application is responsible for closing the source if
The calling application is responsible for closing the stream if
this call returns an error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source,
OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_stream,
const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
......@@ -1333,18 +1335,20 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
For new code, you are likely better off using op_test() instead, which
is less resource-intensive, requires less data to succeed, and imposes a
hard limit on the amount of data it examines (important for unseekable
sources, where all such data must be buffered until you are sure of the
streams, where all such data must be buffered until you are sure of the
stream type).
\param _source The stream to read from (e.g., a <code>FILE *</code>).
\param _stream The stream to read from (e.g., a <code>FILE *</code>).
This value will be passed verbatim as the first
argument to all of the callbacks.
\param _cb The callbacks with which to access the stream.
<code><a href="#op_read_func">read()</a></code> must
be implemented.
<code><a href="#op_seek_func">seek()</a></code> and
<code><a href="#op_tell_func">tell()</a></code> may
be <code>NULL</code>, or may always return -1 to
indicate a source is unseekable, but if
indicate a stream is unseekable, but if
<code><a href="#op_seek_func">seek()</a></code> is
implemented and succeeds on a particular source, then
implemented and succeeds on a particular stream, then
<code><a href="#op_tell_func">tell()</a></code> must
also.
<code><a href="#op_close_func">close()</a></code> may
......@@ -1374,11 +1378,11 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
See op_open_callbacks() for a full list of failure
codes.
\return A partially opened \c OggOpusFile, or <code>NULL</code> on error.
<tt>libopusfile</tt> does <em>not</em> take ownership of the source
<tt>libopusfile</tt> does <em>not</em> take ownership of the stream
if the call fails.
The calling application is responsible for closing the source if
The calling application is responsible for closing the stream if
this call returns an error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_stream,
const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
......@@ -1435,7 +1439,7 @@ void op_free(OggOpusFile *_of);
Their documention will indicate so explicitly.*/
/*@{*/
/**Returns whether or not the data source being read is seekable.
/**Returns whether or not the stream being read is seekable.
This is true if
<ol>
<li>The <code><a href="#op_seek_func">seek()</a></code> and
......@@ -1456,9 +1460,9 @@ int op_seekable(const OggOpusFile *_of) OP_ARG_NONNULL(1);
return 1.
The actual number of links is not known until the stream is fully opened.
\param _of The \c OggOpusFile from which to retrieve the link count.
\return For fully-open seekable sources, this returns the total number of
\return For fully-open seekable streams, this returns the total number of
links in the whole stream, which will be at least 1.
For partially-open or unseekable sources, this always returns 1.*/
For partially-open or unseekable streams, this always returns 1.*/
int op_link_count(const OggOpusFile *_of) OP_ARG_NONNULL(1);
/**Get the serial number of the given link in a (possibly-chained) Ogg Opus
......@@ -1472,7 +1476,7 @@ int op_link_count(const OggOpusFile *_of) OP_ARG_NONNULL(1);
\return The serial number of the given link.
If \a _li is greater than the total number of links, this returns
the serial number of the last link.
If the source is not seekable, this always returns the serial number
If the stream is not seekable, this always returns the serial number
of the current link.*/
opus_uint32 op_serialno(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
......@@ -1489,7 +1493,7 @@ opus_uint32 op_serialno(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
\return The channel count of the given link.
If \a _li is greater than the total number of links, this returns
the channel count of the last link.
If the source is not seekable, this always returns the channel count
If the stream is not seekable, this always returns the channel count
of the current link.*/
int op_channel_count(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
......@@ -1508,9 +1512,9 @@ int op_channel_count(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
compressed size of link \a _li if it is non-negative, or a negative
value on error.
The compressed size of the entire stream may be smaller than that
of the underlying source if trailing garbage was detected in the
of the underlying stream if trailing garbage was detected in the
file.
\retval #OP_EINVAL The source is not seekable (so we can't know the length),
\retval #OP_EINVAL The stream is not seekable (so we can't know the length),
\a _li wasn't less than the total number of links in
the stream, or the stream was only partially open.*/
opus_int64 op_raw_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
......@@ -1528,7 +1532,7 @@ opus_int64 op_raw_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
\return The PCM length of the entire stream if \a _li is negative, the PCM
length of link \a _li if it is non-negative, or a negative value on
error.
\retval #OP_EINVAL The source is not seekable (so we can't know the length),
\retval #OP_EINVAL The stream is not seekable (so we can't know the length),
\a _li wasn't less than the total number of links in
the stream, or the stream was only partially open.*/
ogg_int64_t op_pcm_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
......@@ -1641,10 +1645,10 @@ ogg_int64_t op_pcm_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
/*@{*/
/**\name Functions for seeking in Opus streams
These functions let you seek in Opus streams, if the underlying source
These functions let you seek in Opus streams, if the underlying stream
support it.
Seeking is implemented for all built-in stream I/O routines, though some
individual sources may not be seekable (pipes, live HTTP streams, or HTTP
individual streams may not be seekable (pipes, live HTTP streams, or HTTP
streams from a server that does not support <code>Range</code> requests).
op_raw_seek() is the fastest: it is guaranteed to perform at most one
......
......@@ -153,16 +153,16 @@ struct OggOpusLink{
};
struct OggOpusFile{
/*The callbacks used to access the data source.*/
/*The callbacks used to access the stream.*/
OpusFileCallbacks callbacks;
/*A FILE *, memory buffer, etc.*/
void *source;
/*Whether or not we can seek with this data source.*/
void *stream;
/*Whether or not we can seek with this stream.*/
int seekable;
/*The number of links in this chained Ogg Opus file.*/
int nlinks;
/*The cached information from each link in a chained Ogg Opus file.
If source isn't seekable (e.g., it's a pipe), only the current link
If stream isn't seekable (e.g., it's a pipe), only the current link
appears.*/
OggOpusLink *links;
/*The number of serial numbers from a single link.*/
......@@ -179,9 +179,9 @@ struct OggOpusFile{
After a call to op_get_next_page(), this will point to the first byte after
that page.*/
opus_int64 offset;
/*The total size of this data source, or -1 if it's unseekable.*/
/*The total size of this stream, or -1 if it's unseekable.*/
opus_int64 end;
/*Used to locate pages in the data source.*/
/*Used to locate pages in the stream.*/
ogg_sync_state oy;
/*One of OP_NOTOPEN, OP_PARTOPEN, OP_OPENED, OP_STREAMSET, OP_INITSET.*/
int ready_state;
......
......@@ -148,7 +148,7 @@ static int op_get_data(OggOpusFile *_of,int _nbytes){
int nbytes;
OP_ASSERT(_nbytes>0);
buffer=(unsigned char *)ogg_sync_buffer(&_of->oy,_nbytes);
nbytes=(int)(*_of->callbacks.read)(_of->source,buffer,_nbytes);
nbytes=(int)(*_of->callbacks.read)(_of->stream,buffer,_nbytes);
OP_ASSERT(nbytes<=_nbytes);
if(OP_LIKELY(nbytes>0))ogg_sync_wrote(&_of->oy,nbytes);
return nbytes;
......@@ -158,7 +158,7 @@ static int op_get_data(OggOpusFile *_of,int _nbytes){
static int op_seek_helper(OggOpusFile *_of,opus_int64 _offset){
if(_offset==_of->offset)return 0;
if(_of->callbacks.seek==NULL
||(*_of->callbacks.seek)(_of->source,_offset,SEEK_SET)){
||(*_of->callbacks.seek)(_of->stream,_offset,SEEK_SET)){
return OP_EREAD;
}
_of->offset=_offset;
......@@ -166,7 +166,7 @@ static int op_seek_helper(OggOpusFile *_of,opus_int64 _offset){
return 0;
}
/*Get the current position indicator of the underlying source.
/*Get the current position indicator of the underlying stream.
This should be the same as the value reported by tell().*/
static opus_int64 op_position(const OggOpusFile *_of){
/*The current position indicator is _not_ simply offset.
......@@ -370,7 +370,7 @@ static int op_get_prev_page_serial(OggOpusFile *_of,OpusSeekRecord *_sr,
search_start=llret+1;
}
/*We started from the beginning of the stream and found nothing.
This should be impossible unless the contents of the source changed out
This should be impossible unless the contents of the stream changed out
from under us after we read from it.*/
if(OP_UNLIKELY(!begin)&&OP_UNLIKELY(_offset<0))return OP_EBADLINK;
/*Bump up the chunk size.
......@@ -456,7 +456,7 @@ static opus_int64 op_get_last_page(OggOpusFile *_of,ogg_int64_t *_gp,
}
}
/*We started from at or before the beginning of the link and found nothing.
This should be impossible unless the contents of the source changed out
This should be impossible unless the contents of the stream changed out
from under us after we read from it.*/
if((OP_UNLIKELY(left_link)||OP_UNLIKELY(!begin))&&OP_UNLIKELY(_offset<0)){
return OP_EBADLINK;
......@@ -1395,8 +1395,8 @@ static int op_open_seekable2_impl(OggOpusFile *_of){
opus_int64 data_offset;
int ret;
/*We can seek, so set out learning all about this file.*/
(*_of->callbacks.seek)(_of->source,0,SEEK_END);
_of->offset=_of->end=(*_of->callbacks.tell)(_of->source);
(*_of->callbacks.seek)(_of->stream,0,SEEK_END);
_of->offset=_of->end=(*_of->callbacks.tell)(_of->stream);
if(OP_UNLIKELY(_of->end<0))return OP_EREAD;
data_offset=_of->links[0].data_offset;
if(OP_UNLIKELY(_of->end<data_offset))return OP_EBADLINK;
......@@ -1441,7 +1441,7 @@ static int op_open_seekable2(OggOpusFile *_of){
prev_page_offset=_of->prev_page_offset;
start_offset=_of->offset;
memcpy(op_start,_of->op,sizeof(*op_start)*start_op_count);
OP_ASSERT((*_of->callbacks.tell)(_of->source)==op_position(_of));
OP_ASSERT((*_of->callbacks.tell)(_of->stream)==op_position(_of));
ogg_sync_init(&_of->oy);
ogg_stream_init(&_of->os,-1);
ret=op_open_seekable2_impl(_of);
......@@ -1459,7 +1459,7 @@ static int op_open_seekable2(OggOpusFile *_of){
_of->cur_discard_count=_of->links[0].head.pre_skip;
if(OP_UNLIKELY(ret<0))return ret;
/*And restore the position indicator.*/
ret=(*_of->callbacks.seek)(_of->source,op_position(_of),SEEK_SET);
ret=(*_of->callbacks.seek)(_of->stream,op_position(_of),SEEK_SET);
return OP_UNLIKELY(ret<0)?OP_EREAD:0;
}
......@@ -1498,11 +1498,11 @@ static void op_clear(OggOpusFile *_of){
_ogg_free(_of->serialnos);
ogg_stream_clear(&_of->os);
ogg_sync_clear(&_of->oy);
if(_of->callbacks.close!=NULL)(*_of->callbacks.close)(_of->source);
if(_of->callbacks.close!=NULL)(*_of->callbacks.close)(_of->stream);
}
static int op_open1(OggOpusFile *_of,
void *_source,const OpusFileCallbacks *_cb,
void *_stream,const OpusFileCallbacks *_cb,
const unsigned char *_initial_data,size_t _initial_bytes){
ogg_page og;
ogg_page *pog;
......@@ -1511,7 +1511,7 @@ static int op_open1(OggOpusFile *_of,
memset(_of,0,sizeof(*_of));
if(OP_UNLIKELY(_initial_bytes>(size_t)LONG_MAX))return OP_EFAULT;
_of->end=-1;
_of->source=_source;
_of->stream=_stream;
*&_of->callbacks=*_cb;
/*At a minimum, we need to be able to read data.*/
if(OP_UNLIKELY(_of->callbacks.read==NULL))return OP_EREAD;
......@@ -1532,12 +1532,12 @@ static int op_open1(OggOpusFile *_of,
}
/*Can we seek?
Stevens suggests the seek test is portable.*/
seekable=_cb->seek!=NULL&&(*_cb->seek)(_source,0,SEEK_CUR)!=-1;
seekable=_cb->seek!=NULL&&(*_cb->seek)(_stream,0,SEEK_CUR)!=-1;
/*If seek is implemented, tell must also be implemented.*/
if(seekable){
opus_int64 pos;
if(OP_UNLIKELY(_of->callbacks.tell==NULL))return OP_EINVAL;
pos=(*_of->callbacks.tell)(_of->source);
pos=(*_of->callbacks.tell)(_of->stream);
/*If the current position is not equal to the initial bytes consumed,
absolute seeking will not work.*/
if(OP_UNLIKELY(pos!=(opus_int64)_initial_bytes))return OP_EINVAL;
......@@ -1596,14 +1596,14 @@ static int op_open2(OggOpusFile *_of){
return ret;
}
OggOpusFile *op_test_callbacks(void *_source,const OpusFileCallbacks *_cb,
OggOpusFile *op_test_callbacks(void *_stream,const OpusFileCallbacks *_cb,
const unsigned char *_initial_data,size_t _initial_bytes,int *_error){
OggOpusFile *of;
int ret;
of=(OggOpusFile *)_ogg_malloc(sizeof(*of));
ret=OP_EFAULT;
if(OP_LIKELY(of!=NULL)){
ret=op_open1(of,_source,_cb,_initial_data,_initial_bytes);
ret=op_open1(of,_stream,_cb,_initial_data,_initial_bytes);
if(OP_LIKELY(ret>=0)){
if(_error!=NULL)*_error=0;
return of;
......@@ -1617,10 +1617,10 @@ OggOpusFile *op_test_callbacks(void *_source,const OpusFileCallbacks *_cb,
return NULL;
}
OggOpusFile *op_open_callbacks(void *_source,const OpusFileCallbacks *_cb,
OggOpusFile *op_open_callbacks(void *_stream,const OpusFileCallbacks *_cb,
const unsigned char *_initial_data,size_t _initial_bytes,int *_error){
OggOpusFile *of;
of=op_test_callbacks(_source,_cb,_initial_data,_initial_bytes,_error);
of=op_test_callbacks(_stream,_cb,_initial_data,_initial_bytes,_error);
if(OP_LIKELY(of!=NULL)){
int ret;
ret=op_open2(of);
......@@ -1633,15 +1633,15 @@ OggOpusFile *op_open_callbacks(void *_source,const OpusFileCallbacks *_cb,
/*Convenience routine to clean up from failure for the open functions that
create their own streams.*/
static OggOpusFile *op_open_close_on_failure(void *_source,
static OggOpusFile *op_open_close_on_failure(void *_stream,
const OpusFileCallbacks *_cb,int *_error){
OggOpusFile *of;
if(OP_UNLIKELY(_source==NULL)){
if(OP_UNLIKELY(_stream==NULL)){
if(_error!=NULL)*_error=OP_EFAULT;
return NULL;
}
of=op_open_callbacks(_source,_cb,NULL,0,_error);
if(OP_UNLIKELY(of==NULL))(*_cb->close)(_source);
of=op_open_callbacks(_stream,_cb,NULL,0,_error);
if(OP_UNLIKELY(of==NULL))(*_cb->close)(_stream);
return of;
}
......@@ -1659,15 +1659,15 @@ OggOpusFile *op_open_memory(const unsigned char *_data,size_t _size,
/*Convenience routine to clean up from failure for the open functions that
create their own streams.*/
static OggOpusFile *op_test_close_on_failure(void *_source,
static OggOpusFile *op_test_close_on_failure(void *_stream,
const OpusFileCallbacks *_cb,int *_error){
OggOpusFile *of;
if(OP_UNLIKELY(_source==NULL)){
if(OP_UNLIKELY(_stream==NULL)){
if(_error!=NULL)*_error=OP_EFAULT;
return NULL;
}
of=op_test_callbacks(_source,_cb,NULL,0,_error);
if(OP_UNLIKELY(of==NULL))(*_cb->close)(_source);
of=op_test_callbacks(_stream,_cb,NULL,0,_error);
if(OP_UNLIKELY(of==NULL))(*_cb->close)(_stream);
return of;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment