ref: c59d42b6fb4bb2b7e8c7debfa816e2641fd998b6
parent: 881a54dad434a0939c84c73ebc513a11bcb6078a
author: Timothy B. Terriberry <tterribe@xiph.org>
date: Fri Jul 7 10:36:18 EDT 2017
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.
--- a/include/opusfile.h
+++ b/include/opusfile.h
@@ -1155,7 +1155,9 @@
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.
@@ -1162,9 +1164,9 @@
<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 @@
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,9 +1335,11 @@
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.
@@ -1342,9 +1346,9 @@
<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 @@
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 @@
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 @@
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 @@
\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 @@
\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 @@
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 @@
\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 @@
/*@{*//**\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
--- a/src/internal.h
+++ b/src/internal.h
@@ -153,16 +153,16 @@
};
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 @@
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;
--- a/src/opusfile.c
+++ b/src/opusfile.c
@@ -148,7 +148,7 @@
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_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 @@
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 @@
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 @@
}
}
/*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 @@
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 @@
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 @@
_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 @@
_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 @@
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 @@
}
/*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,7 +1596,7 @@
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;
@@ -1603,7 +1603,7 @@
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 @@
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 @@
/*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 @@
/*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;
}